# 附录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 命令速查（建议作为一线排障入口）

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

```bash
openclaw doctor
openclaw health --json
openclaw status --deep
openclaw channels capabilities
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 或业务代码问题”。