# 附录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
openclaw models status --probe
openclaw logs --follow --json
```

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

## D.3 WebSocket 与事件流参考

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

* Gateway 协议：<https://docs.openclaw.ai/gateway/protocol>
* Gap recovery 与运维 Runbook：<https://docs.openclaw.ai/gateway/index#gap-recovery>
* 设备配对与信任管理：<https://docs.openclaw.ai/cli/devices>

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

1. 连接层可恢复（心跳、重连、恢复点）。
2. 事件层可对账（event id、`seq`、`stateVersion`、幂等键、错误分类；`traceId` 只在日志或 payload 明确提供时保留）。
3. 执行层可限权（工具策略与沙箱约束）。

## D.4 SDK 与集成建议

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

1. 先用 CLI 跑通完整链路并固化验收命令。
2. 再在应用层封装调用，并保留 request id / idempotency key、event id / seq / stateVersion 与错误分类；若日志或 payload 暴露 `traceId`，再把它作为链路回放辅助字段保存。
3. 最后把回退、重试、超时和审计接入统一运行手册。

配置与沙箱相关声明不要只靠文档记忆：用 `openclaw config schema` / `openclaw config validate` 证明 schema，用 `openclaw sandbox explain --json` 证明当前 agent / session 的有效沙箱与工具边界。

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/openclaw_guide/fu-lu/appendix/api_reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.