openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 01:04:02 +00:00
parent fc871056b8
commit d4d0980db6
1 changed files with 180 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

434
docs/zh-CN/concepts/openclaw-sdk.md
View File

@ -1,129 +1,120 @@
---
read_when:
- 你正在设计或实现一个公开的 OpenClaw 应用 SDK
- 你正在将 OpenClaw 智能体 API 与 Cursor、Claude Agent SDK、OpenAI Agents、Google ADK、OpenCode、Codex 或 ACP 进行比较
- 你需要判断某项功能应归属于公共应用 SDK、插件 SDK、Gateway 网关协议、ACP 后端，还是托管环境层。
- 你正在构建一个与 OpenClaw 通信的外部应用、脚本、仪表板、CI 作业或 IDE 扩展
- 你正在选择应用 SDK 还是插件 SDK
- 你正在与 Gateway 网关的智能体运行、会话、事件、审批、模型或工具集成
sidebarTitle: App SDK
summary: 面向外部应用、脚本、仪表板、CI 作业和 IDE 扩展的公共 OpenClaw 应用 SDK 设计
summary: 面向外部应用、脚本、仪表盘、CI 作业和 IDE 扩展的公开 OpenClaw 应用 SDK
title: OpenClaw 应用 SDK
x-i18n:
generated_at: "2026-04-30T00:51:05Z"
generated_at: "2026-04-30T01:03:29Z"
model: gpt-5.5
provider: openai
source_hash: 227d3baf3aaf54bf35288214b051e2e284280165e1283d476594feda26d56bb9
source_hash: 9c46454d172a25d329a796461982dc4307d3720a28df777eda8605996505e38c
source_path: concepts/openclaw-sdk.md
workflow: 16
---
本页是公开 **OpenClaw 应用 SDK** 的设计提案。它与现有的[插件 SDK](/zh-CN/plugins/sdk-overview) 分开。
**OpenClaw 应用 SDK** 是 OpenClaw 进程外应用的公开客户端 API。当脚本、仪表板、CI 作业、IDE 扩展或其他外部应用需要连接到 Gateway 网关、启动智能体运行、流式传输事件、等待结果、取消工作或检查 Gateway 网关资源时，请使用 `@openclaw/sdk`。
<Note>
当外部应用、脚本、仪表板、CI 作业或 IDE
扩展想通过 Gateway 网关运行并观测 OpenClaw 智能体时，请使用 `@openclaw/sdk`。只有在编写运行于 OpenClaw 内部的插件时，才使用
`openclaw/plugin-sdk/*`。
应用 SDK 不同于[插件 SDK](/zh-CN/plugins/sdk-overview)。
`@openclaw/sdk` 从 OpenClaw 外部与 Gateway 网关通信。
`openclaw/plugin-sdk/*` 仅用于在 OpenClaw 内部运行并注册提供商、渠道、工具、钩子或受信任运行时的插件。
</Note>
插件 SDK 面向运行于 OpenClaw 内部并扩展提供商、渠道、工具、钩子和可信运行时的代码。应用 SDK 应面向希望通过稳定公开 API 运行并观测 OpenClaw 智能体的外部应用、脚本、仪表板、CI 作业、IDE 扩展和自动化系统。
## 今天发布的内容
## Status
`@openclaw/sdk` 包含：
架构草案。
| 接口 | Status | 功能 |
| ------------------------- | ---------- | ---------------------------------------------------------------------------- |
| `OpenClaw` | 就绪 | 主客户端入口点。负责传输、连接、请求和事件。 |
| `GatewayClientTransport` | 就绪 | 由 Gateway 网关客户端支持的 WebSocket 传输。 |
| `oc.agents` | 就绪 | 列出、创建、更新、删除和获取智能体句柄。 |
| `Agent.run()` | 就绪 | 启动 Gateway 网关 `agent` 运行并返回 `Run`。 |
| `oc.runs` | 就绪 | 创建、获取、等待、取消和流式传输运行。 |
| `Run.events()` | 就绪 | 流式传输标准化的逐运行事件，并为快速运行提供重放。 |
| `Run.wait()` | 就绪 | 调用 `agent.wait` 并返回稳定的 `RunResult`。 |
| `Run.cancel()` | 就绪 | 按运行 ID 调用 `sessions.abort`，可用时附带会话键。 |
| `oc.sessions` | 就绪 | 创建、解析、发送到、修补、压缩和获取会话句柄。 |
| `Session.send()` | 就绪 | 调用 `sessions.send` 并返回 `Run`。 |
| `oc.models` | 就绪 | 调用 `models.list` 和当前的 `models.authStatus` Status RPC。 |
| `oc.tools` | 部分支持 | 列出工具目录和有效工具；尚未接入直接工具调用。 |
| `oc.approvals` | 就绪 | 通过 Gateway 网关审批 RPC 列出和解析 exec 审批。 |
| `oc.rawEvents()` | 就绪 | 为高级使用者暴露原始 Gateway 网关事件。 |
| `normalizeGatewayEvent()` | 就绪 | 将原始 Gateway 网关事件转换为稳定的 SDK 事件形态。 |
本文档记录了对以下智能体 SDK 和运行时表面进行比较评审后形成的设计方向：
SDK 还导出这些接口使用的核心类型：
`AgentRunParams`, `RunResult`, `RunStatus`, `OpenClawEvent`,
`OpenClawEventType`, `GatewayEvent`, `OpenClawTransport`,
`GatewayRequestOptions`, `SessionCreateParams`, `SessionSendParams`,
`RuntimeSelection`, `EnvironmentSelection`, `WorkspaceSelection`,
`ApprovalMode` 以及相关结果类型。
| 项目 | 有用经验 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cursor SDK cookbook | 最佳高级产品 API：`Agent`、`Run`、本地和云端运行时、流式传输、取消、模型发现、代码库、制品以及云端 pull request 流程。 |
| Claude Agent SDK | 强大的双向会话客户端、中断和 Steering 支持、权限模式、钩子、自定义工具、会话存储以及可恢复转录。 |
| OpenAI Agents SDK | 强大的工作流概念：交接、护栏、人工审批、追踪、运行状态、流式结果对象以及中断后的恢复。 |
| Google ADK | 强大的内部架构：运行器、会话服务、记忆服务、制品服务、凭证服务、插件、事件操作以及长时间运行工具确认。 |
| OpenCode | 强大的客户端/服务器形态：生成的 API 客户端、REST 加 SSE、会话、工作区、worktree、权限、问题、文件、VCS、PTY、工具、智能体、Skills 和 MCP。 |
| Codex | 强大的本地运行时边界：审批、沙箱隔离、网络策略、本地和远程 exec 服务器、结构化协议事件以及线程感知的 app-server 会话。 |
| ACP and acpx | 面向外部编码 harness 的强互操作层，支持命名会话、提示队列、协作式取消和运行时适配器。 |
## 连接到 Gateway 网关
建议是在 OpenCode 风格生成式 Gateway 网关客户端之上构建一个像 Cursor 一样简单的公开门面，同时在适合的地方将 Claude、OpenAI Agents、ADK、Codex 和 ACP 概念保留为内部设计参考。
## 目标
- 为应用开发者提供一个小型高级 API，用于运行 OpenClaw 智能体。
- 保持本地优先的 OpenClaw 作为默认运行时。
- 将云端或托管环境作为增量式环境提供商，而不是不同的智能体 API。
- 保留现有 OpenClaw 边界：Gateway 网关拥有公开协议，插件 SDK 拥有进程内扩展，ACP 拥有外部 harness 互操作。
- 将 `stream`、`wait`、`cancel`、`resume`、`fork`、制品、审批和后台任务作为一等操作来支持。
- 暴露稳定的规范化事件，同时为高级消费者保留运行时原生原始事件。
- 明确 SDK 权限、密钥转发、审批、沙箱隔离和远程环境。
- 让公开契约足够小，便于文档化、测试、版本化和生成。
## 非目标
- 不将 `openclaw/plugin-sdk/*` 暴露为应用 SDK。
- 不让 ACP 成为唯一的运行时模型。
- 不要求必须有云服务后 SDK 才有用。
- 不精确克隆 Cursor、Claude、OpenAI、ADK、OpenCode、Codex 或 ACP API。
- 不将无界的 `any` 事件载荷作为唯一公开契约暴露。
- 除非所选环境确实可以强制执行，否则不承诺外部 harness 的沙箱或网络隔离。
- 不让插件作者在插件运行时代码中依赖应用 SDK 对象。
## OpenClaw 当前适配情况
OpenClaw 已经具备大部分基础：
| 现有表面 | 贡献内容 |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [Agent loop](/zh-CN/concepts/agent-loop) | `agent` 和 `agent.wait` 运行生命周期、流式传输、超时和会话序列化。 |
| [Agent Runtimes](/zh-CN/concepts/agent-runtimes) | 提供商、模型、运行时和渠道分离。 |
| [ACP agents](/zh-CN/tools/acp-agents) | 面向 Claude Code、Cursor、Gemini CLI、OpenCode、显式 Codex ACP 以及类似工具的外部 harness 会话。 |
| [后台任务](/zh-CN/automation/tasks) | 面向 ACP、子智能体、cron、CLI 操作和异步媒体作业的分离式活动账本。 |
| [子智能体](/zh-CN/tools/subagents) | 隔离的后台智能体运行、可选的 fork 上下文，以及向请求方会话回传。 |
| [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness) | 面向 Codex 等嵌入式 harness 的可信原生运行时注册。 |
| Gateway 网关协议 schema | 当前用于智能体参数、会话、订阅、中止、压缩和检查点的类型化方法与事件定义。 |
缺口不是智能体执行。缺口是这些组件之上的稳定、友好的公开门面。
## 核心模型
应用 SDK 应使用一小组稳定名词。
| 名词 | 含义 |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `OpenClaw` | 客户端入口点。拥有 Gateway 网关发现、认证、低层客户端访问和命名空间工厂。 |
| `Agent` | 已配置的执行者。携带智能体 ID、默认模型、默认运行时、默认工具策略和面向应用的辅助方法。 |
| `Session` | 持久转录、路由、工作区、上下文和运行时绑定。 |
| `Run` | 一次提交的轮次或任务。流式传输事件、等待结果、取消并暴露制品。 |
| `Task` | 分离式或后台活动账本条目。覆盖子智能体、ACP 派生、cron 作业、CLI 运行和异步作业。 |
| `Artifact` | 文件、补丁、diff、媒体、日志、轨迹、pull request、截图和生成的 bundle。 |
| `Environment` | 运行执行的位置：本地 Gateway 网关、本地工作区、节点主机、ACP harness、托管运行器或未来的云工作区。 |
| `ToolSpace` | 有效工具表面：OpenClaw 工具、MCP 服务器、渠道工具、应用工具、审批规则和工具元数据。 |
| `Approval` | 由运行、工具、环境或 harness 请求的人工或策略决策。 |
这些名词能够清晰映射到现有 OpenClaw 概念，同时避免泄露实现特定名称，例如 PI 运行器内部机制、插件 harness 注册或 ACP 适配器细节。
## 产品形态
高级 SDK 应该像这样使用：
使用显式 Gateway 网关 URL 创建客户端，或为测试和嵌入式应用运行时注入自定义传输。
```typescript
import { OpenClaw } from "@openclaw/sdk";
const oc = new OpenClaw({ gateway: "auto" });
const oc = new OpenClaw({
url: "ws://127.0.0.1:14565",
token: process.env.OPENCLAW_GATEWAY_TOKEN,
requestTimeoutMs: 30_000,
});
await oc.connect();
```
`new OpenClaw({ gateway: "ws://..." })` 等同于 `url`。构造函数接受 `gateway: "auto"` 选项，但自动 Gateway 网关设备发现尚不是独立的 SDK 功能；当应用本身还不知道如何发现 Gateway 网关时，请传入 `url`。
对于测试，传入一个实现 `OpenClawTransport` 的对象：
```typescript
const oc = new OpenClaw({
transport: {
async request(method, params) {
return { method, params };
},
async *events() {},
},
});
```
## 运行智能体
当应用需要智能体句柄时，使用 `oc.agents.get(id)`，然后调用 `agent.run()`。
```typescript
const agent = await oc.agents.get("main");
const run = await agent.run({
input: "Review this pull request and suggest the smallest safe fix.",
model: "openai/gpt-5.5",
sessionKey: "main",
timeoutMs: 30_000,
});
for await (const event of run.events()) {
if (event.type === "assistant.delta") {
process.stdout.write(event.text);
const data = event.data as { delta?: unknown };
if (event.type === "assistant.delta" && typeof data.delta === "string") {
process.stdout.write(data.delta);
}
}
const result = await run.wait();
const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);
```
同一个应用应该能够使用持久会话：
像 `openai/gpt-5.5` 这样的提供商限定模型引用会拆分为 Gateway 网关的 `provider` 和 `model` 覆盖项。`timeoutMs` 在 SDK 中保持为毫秒，并会为 `agent` RPC 转换为 Gateway 网关超时秒数。
`run.wait()` 使用 Gateway 网关的 `agent.wait` RPC。当等待截止时间到期但运行仍处于活动状态时，会返回 `status: "accepted"`，而不是假装运行本身已超时。运行时超时、中止的运行和取消的运行会标准化为 `timed_out` 或 `cancelled`。
## 创建和复用会话
当应用需要持久的转录状态时，请使用会话。
```typescript
const session = await oc.sessions.create({
@ -135,212 +126,147 @@ const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
```
当前实现说明：`@openclaw/sdk` 从现有的 Gateway 网关后端表面开始。像 `openai/gpt-5.5` 这样的提供商限定模型引用会拆分为 Gateway 网关 `provider` 和 `model` 覆盖项。按运行指定的 `workspace`、`runtime`、`environment` 和 `approvals` 选择仍是设计目标；当调用方设置这些选项时，客户端会抛出错误，以免请求静默地使用默认值执行。任务、制品、环境和通用工具调用辅助方法也已搭建为未来 API 形态，并会在 Gateway 网关 RPC 存在前抛出明确的不支持错误。
同一个 API 还应该能够使用外部 ACP harness：
`Session.send()` 调用 `sessions.send` 并返回 `Run`。会话句柄还支持：
```typescript
const run = await oc.runs.create({
input: "Deep review this repository and return only high-risk findings.",
workspace: { cwd: process.cwd() },
runtime: { type: "acp", harness: "claude" },
mode: "task",
});
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });
```
托管环境不应改变顶层 API：
## 流式传输事件
SDK 会将原始 Gateway 网关事件标准化为稳定的 `OpenClawEvent` 信封：
```typescript
const run = await agent.run({
input: "Run the full changed gate and summarize failures.",
workspace: { repo: "openclaw/openclaw", ref: "main" },
runtime: {
type: "managed",
provider: "testbox",
timeoutMinutes: 90,
},
});
type OpenClawEvent = {
version: 1;
id: string;
ts: number;
type: OpenClawEventType;
runId?: string;
sessionId?: string;
sessionKey?: string;
taskId?: string;
agentId?: string;
data: unknown;
raw?: GatewayEvent;
};
```
## 运行时选择
常见事件类型包括：
应用 SDK 应将运行时选择暴露为规范化 union：
| 事件类型 | 来源 Gateway 网关事件 |
| --------------------- | ----------------------------------------- |
| `run.started` | `agent` 生命周期开始 |
| `run.completed` | `agent` 生命周期结束 |
| `run.failed` | `agent` 生命周期错误 |
| `run.cancelled` | 已中止/已取消的生命周期结束 |
| `run.timed_out` | 超时生命周期结束 |
| `assistant.delta` | Assistant 流式传输增量 |
| `assistant.message` | Assistant 消息 |
| `thinking.delta` | 思考或计划流 |
| `tool.call.started` | 工具/项目/命令开始 |
| `tool.call.delta` | 工具/项目/命令更新 |
| `tool.call.completed` | 工具/项目/命令完成 |
| `tool.call.failed` | 工具/项目/命令失败或被阻止状态 |
| `approval.requested` | Exec 或插件审批请求 |
| `approval.resolved` | Exec 或插件审批解析 |
| `session.created` | `sessions.changed` 创建 |
| `session.updated` | `sessions.changed` 更新 |
| `session.compacted` | `sessions.changed` 压缩 |
| `task.updated` | 任务更新事件 |
| `artifact.updated` | 补丁流事件 |
| `raw` | 尚未有稳定 SDK 映射的任意事件 |
`Run.events()` 会将事件筛选到一个运行 ID，并为快速运行重放已看到的事件。这意味着以下记录的流程是安全的：
```typescript
type RuntimeSelection =
| "auto"
| { type: "embedded"; id: "pi" | "codex" | string }
| { type: "cli"; id: "claude-cli" | string }
| { type: "acp"; harness: "claude" | "cursor" | "gemini" | "opencode" | string }
| { type: "managed"; provider: "local" | "node" | "testbox" | "cloud" | string };
const run = await agent.run("Summarize the latest session.");
for await (const event of run.events()) {
if (event.type === "run.completed") {
break;
}
}
```
规则：
对于应用范围的流，请使用 `oc.events()`。对于原始 Gateway 网关帧，请使用 `oc.rawEvents()`。
- `auto` 遵循 OpenClaw 运行时选择规则。
- `embedded` 指向通过插件 SDK 注册的可信进程内 harness，例如 `pi` 或 `codex`。
- `cli` 在可用时指向 OpenClaw 拥有的 CLI 后端执行。
- `acp` 通过 ACP/acpx 指向外部 harness。
- `managed` 指向环境提供商，并且仍可能在该环境内运行嵌入式、CLI 或 ACP 运行时。
## 模型、工具和审批
运行时选择对象应该是描述性的。它不应该成为隐藏密钥处理、沙箱策略或工作区预配的地方。
## 环境模型
环境是执行基础层。它应该是显式的，因为本地 CLI 运行、外部 harness、节点主机和云工作区具有不同的安全性与生命周期属性。
模型助手映射到当前 Gateway 网关方法：
```typescript
type EnvironmentSelection =
| { type: "local"; cwd?: string }
| { type: "gateway"; url?: string; cwd?: string }
| { type: "node"; nodeId: string; cwd?: string }
| { type: "managed"; provider: string; repo?: string; ref?: string }
| { type: "ephemeral"; provider: string; repo?: string; ref?: string };
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
```
环境拥有：
工具助手暴露 Gateway 网关目录和有效工具视图：
- checkout 或工作区准备
- 进程和文件访问
- 沙箱和网络强制执行
- 环境变量和密钥引用
- 日志、追踪和制品
- 清理和保留
- 运行时可用性
```typescript
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
```
这种分离让托管智能体成为 SDK 的自然扩展。托管智能体是在托管环境中的普通运行，而不是特殊的产品分支。
审批助手使用 exec 审批 RPC：
详细的命名空间、事件、结果、审批、制品、安全、包和环境提供商契约位于
[OpenClaw 应用 SDK API 设计](/zh-CN/reference/openclaw-sdk-api-design)。
```typescript
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
```
## 实践手册计划
## 今天明确不支持的内容
SDK 应随附能力扩展手册，而不只是参考文档。
SDK 包含我们想要的产品模型名称，但不会静默假装 Gateway 网关 RPC 存在。这些调用目前会抛出明确的不支持错误：
推荐示例：
```typescript
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");
| 示例 | 展示内容 |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| 快速开始 | 创建客户端、运行智能体、流式传输输出、等待结果。 |
| 编码智能体 CLI | 本地工作区、模型选择器、取消、审批、JSON 输出。 |
| 智能体仪表盘 | 会话、运行、后台任务、工件、事件回放、Status 筛选器。 |
| 应用构建器 | 智能体在预览服务器并行运行时编辑工作区。 |
| 拉取请求审查器 | 针对仓库引用运行，收集 diff 评论和工件。 |
| 审批控制台 | 订阅审批，并从 UI 回答审批。 |
| ACP harness 运行器 | 使用同一个 `Run` API 通过 ACP 运行 Claude Code、Cursor、Gemini CLI 或 OpenCode。 |
| 托管环境提供商 | 最小提供商，用于准备工作区、流式传输事件、保存工件并清理。 |
| Slack 或 Discord 桥接 | 外部应用接收事件并发布进度摘要，而不成为渠道插件。 |
| 多智能体研究 | 生成并行运行、收集工件，并综合生成最终报告。 |
await oc.tools.invoke("tool-name", {});
能力扩展手册示例应优先使用高级 API。低级生成式
客户端示例应放在高级章节中。
await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");
## 分阶段实现
await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");
```
### 阶段 0：RFC 与词汇
逐运行的 `workspace`、`runtime`、`environment` 和 `approvals` 字段已按未来形态进行类型定义，但当前 Gateway 网关不支持在 `agent` RPC 上使用这些覆盖项。如果调用方传入它们，SDK 会在提交运行前抛出错误，避免工作意外使用默认工作区、运行时、环境或审批行为执行。
- 就公开名词和名称达成一致。
- 决定包名。
- 定义第一版事件分类法。
- 在文档中标记当前 Plugin SDK 是有意分离的。
## 应用 SDK 与插件 SDK
### 阶段 1：低级生成式客户端
当代码位于 OpenClaw 外部时，使用应用 SDK：
- 从 Gateway 网关协议 schema 生成 TypeScript 客户端。
- 优先覆盖 `agent`、`agent.wait`、会话、订阅、中止和任务。
- 添加冒烟测试，确保生成的方法匹配 Gateway 网关方法名称和 schema
形状。
- 以实验性或内部包发布。
- 启动或观察智能体运行的 Node 脚本
- 调用 Gateway 网关的 CI 作业
- 仪表板和管理面板
- IDE 扩展
- 不需要成为渠道插件的外部桥接
- 使用假的或真实 Gateway 网关传输的集成测试
### 阶段 2：高级运行 API
当代码在 OpenClaw 内部运行时，使用插件 SDK：
- 添加 `OpenClaw`、`Agent`、`Session` 和 `Run`。
- 支持 `run.events()`、`run.wait()` 和 `run.cancel()`。
- 支持本地 Gateway 网关发现和显式 Gateway 网关 URL。
- 支持持久会话和会话发送。
- 提供商插件
- 渠道插件
- 工具或生命周期钩子
- Agent harness plugins
- 受信任运行时助手
### 阶段 3：规范化事件投影
- 在现有原始事件旁边添加 Gateway 网关侧的规范化事件投影。
- 在策略允许的情况下保留原始运行时事件。
- 添加回放游标和重连行为。
- 将 PI、Codex、ACP 和任务事件映射到稳定分类法。
### 阶段 4：工件与审批
- 添加工件列表和下载。
- 添加审批订阅和响应辅助函数。
- 添加问题订阅和响应辅助函数。
- 添加能力扩展手册审批控制台。
### 阶段 5：环境提供商
- 引入本地、节点和托管环境提供商契约。
- 从一个操作上已存在的环境开始。
- 添加工作区准备、日志、工件、超时、清理和保留。
### 阶段 6：云风格工作流
- 添加面向仓库和分支的运行。
- 添加拉取请求工件。
- 添加按仓库、分支、Status 和负责人分组的运行看板。
- 添加长期运行的托管会话和保留策略。
## 可借鉴的设计选择
借鉴这些思路：
- 来自 Cursor：`Agent` 加 `Run`、本地与云端对称、模型发现、
工件，以及由能力扩展手册驱动的新手引导。
- 来自 Claude Agent SDK：双向客户端、中断、权限、钩子、
自定义工具、会话存储和恢复语义。
- 来自 OpenAI Agents：交接、防护栏、人工审批恢复、追踪，以及
结构化的流式传输结果对象。
- 来自 Google ADK：runner 背后的服务、事件动作、记忆、工件、
凭证服务，以及围绕运行生命周期的插件拦截。
- 来自 OpenCode：生成式协议客户端、REST 加 SSE、会话、
工作区、问题、权限、文件、VCS、PTY、MCP、智能体和 Skills。
- 来自 Codex：显式沙箱、审批、网络、本地和远程执行，以及
应用服务器线程边界。
- 来自 ACP 和 acpx：基于适配器的外部 harness 互操作性和命名
prompt 队列。
## 应避免的设计选择
避免这些陷阱：
- 只是 Gateway 网关内部机制的薄封装公开 SDK。
- 导入 Plugin SDK 子路径的公开 SDK。
- 事件只有 `stream` 加 `data` 的公开 SDK。
- 让本地 OpenClaw 感觉像旧版模式的云优先 API。
- 隐藏在模型 ID 前缀中的运行时选择。
- 隐藏在环境映射中的密钥转发。
- 每次运行顶层都有 ACP 特定选项。
- 所选运行时无法强制执行的沙箱标志。
- 一个 SDK 对象同时试图成为提供商插件、渠道插件、应用客户端
和托管 runner。
## 未决问题
- 初始包应放在此仓库中，还是单独的 SDK 仓库中？
- 低级生成式客户端是否应在高级包装器稳定之前公开发布？
- 第一个受支持的应用认证机制是什么：本地令牌、管理员令牌、
OAuth 设备流，还是已签名的应用注册？
- SDK 默认应暴露多少会话消息历史？
- 托管环境应仅在 Gateway 网关配置中配置，还是 SDK
调用方也可以使用作用域令牌直接请求？
- 本地运行生成的工件适用哪些保留规则？
- 哪些事件载荷在交付给应用之前需要脱敏？
- `Run` 应覆盖普通聊天轮次和分离任务，还是分离的后台工作应始终返回
一个带有嵌套 `Run` 的 `Task` 包装器？
应用 SDK 代码应从 `@openclaw/sdk` 导入。插件代码应从记录在文档中的 `openclaw/plugin-sdk/*` 子路径导入。不要混用这两种契约。
## 相关文档
- [OpenClaw 应用 SDK API 设计](/zh-CN/reference/openclaw-sdk-api-design)
- [Gateway RPC 参考](/zh-CN/reference/rpc)
- [Agent loop](/zh-CN/concepts/agent-loop)
- [Agent Runtimes](/zh-CN/concepts/agent-runtimes)
- [会话](/zh-CN/concepts/session)
- [子智能体](/zh-CN/tools/subagents)
- [后台任务](/zh-CN/automation/tasks)
- [ACP 智能体](/zh-CN/tools/acp-agents)
- [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness)
- [ACP agents](/zh-CN/tools/acp-agents)
- [插件 SDK 概览](/zh-CN/plugins/sdk-overview)