附录D:API 与 SDK 参考

本附录提供“快速定位入口”的参考,不替代 API 文档。字段与接口会随版本变化:若发现字段或命令不同,优先用 CLI 的 --helpstatus --deep/结构化日志自证,再回到 D.2 的最小排障集核对结果。

D.1 控制面入口(官方文档)

建议先确认配置与状态命令可用,再进入接口联调。

D.2 CLI 命令速查(建议作为一线排障入口)

下面是一组推荐的最小排障命令组合,可直接用于环境体检与链路回放。

openclaw doctor
openclaw health --json
openclaw status --deep
openclaw channels status --probe
openclaw models status --check
openclaw logs --follow --json

这些命令覆盖了依赖自检、运行状态、渠道探针、模型探针和链路回放,是最小可复验集。

D.3 WebSocket 与事件流参考

如需对接长连接与事件流,请优先阅读:

接口实现建议遵循三条原则:

  1. 连接层可恢复(心跳、重连、恢复点)。

  2. 事件层可对账(traceId、幂等键、错误分类)。

  3. 执行层可限权(工具策略与沙箱约束)。

D.4 SDK 与集成建议

如需在应用中嵌入 OpenClaw 能力,建议采用“先 CLI 验证、再 SDK/HTTP 集成”的顺序:

  1. 先用 CLI 跑通完整链路并固化验收命令。

  2. 再在应用层封装调用,并保留 traceId 与错误分类。

  3. 最后把回退、重试、超时和审计接入统一运行手册。

这样可以避免把“配置问题”误判为“SDK 或业务代码问题”。

最后更新于