交互式 API Reference

Interactive Reference

查字段、schema、示例与错误码

本页加载静态 openapi.json 并用 Scalar 渲染。若你还在判断“该调用哪类 API”，先看 API 概览；若你已经知道端点，留在本页查请求体、响应示例、鉴权和错误码。

原始 OpenAPI JSON 覆盖矩阵 有效性报告 机器可读报告

文档生成策略

下面的 OpenAPI artifact 是文档侧静态产物，由 route inventory + curated semantic overlay 生成。它不会修改 ClawSentry 运行时 API 行为。

Scalar 资源权衡

本阶段不引入新的构建依赖。页面使用 pinned CDN 版本加载 Scalar API Reference；mkdocs build --strict 不依赖远程 JS 是否可达。若你的环境无法访问 CDN，请直接查看 原始 OpenAPI JSON。页面还对 Scalar 1.52.5 的 Invalid YAML object 已知 false-positive 做了窄范围 console 兼容处理；源 JSON 与有效性报告仍是核验依据。

交接包	用途
openapi.json	前端/SDK/HTTP client 生成与字段核对
api-coverage.json	查看 service、auth、source、Markdown ref 和示例覆盖
validity-report.md	人类可读的 API 真实性核验结果
api-validity.json	可导入脚本或 CI 的机器可读核验结果

如何给前端开发使用

场景	推荐做法
生成类型或 client	使用 openapi.json，只把 public 和明确启用的 enterprise 端点纳入目标环境。
构建 Dashboard 首屏	先接 GET /report/summary、GET /report/sessions、GET /report/session/{session_id}/page。
构建 Enterprise OS 20 类风险统计	企业模式下先接 GET /enterprise/report/live?cached=true；需要审计窗口时再接 GET /enterprise/report/summary?window_seconds=3600，读取 by_trinityguard_subtype / by_trinityguard_tier 或 trinityguard.by_subtype / trinityguard.by_tier。
构建实时流	使用 GET /report/stream；浏览器侧可用 query token，服务端集成优先 Bearer token。
构建处置动作	acknowledge / enforcement / quarantine / L3 advisory 写入端点都按 contract 验证，不在报告生成时盲目 live 调用。
核对 API 是否真实存在	打开 API 有效性报告，查看 source file:line、Markdown anchor 和 OpenAPI operation。

如何阅读这个 Reference

分组	适合读者	你能查到什么
AHP 决策	二次开发者	POST /ahp、POST /ahp/a3s、POST /ahp/codex、POST /ahp/resolve 的请求/响应结构
报表与监控	运维 / 前端	会话、风险、告警、SSE 事件流
L3 Advisory	运维 / 安全审查	snapshot、job、review、full-review 的 advisory-only 边界
Enterprise 条件端点	企业部署运维	/enterprise/* 的条件注册状态，不代表默认环境开启
Excluded	文档维护者	GET /ui、GET /ui/{path:path} 和 webhook-local GET /health 不进入共享 OpenAPI 的原因
Webhook	OpenClaw 集成方	token、HMAC、timestamp、IP allowlist、idempotency 行为