附录D：API 与 SDK 参考

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

D.1 控制面入口（官方文档）

• Gateway 配置总览：https://docs.openclaw.ai/gateway/configuration

• Gateway 安全：https://docs.openclaw.ai/gateway/security

• Channels：https://docs.openclaw.ai/cli/channels

• Models：https://docs.openclaw.ai/cli/models

• Plugins：https://docs.openclaw.ai/cli/plugins

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

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 与事件流参考

如需对接长连接与事件流，请优先阅读：

• Gateway：https://docs.openclaw.ai/gateway

• 多智能体路由：https://docs.openclaw.ai/concepts/multi-agent-routing

• 事件幂等与故障切换：https://docs.openclaw.ai/concepts/model-failover

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

1. 连接层可恢复（心跳、重连、恢复点）。

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

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

D.4 SDK 与集成建议

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

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

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

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

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