OpenClaw App SDK API 设计

@openclaw/sdk 是面向外部应用/客户端的公共 SDK，用于与 Gateway 通信。与 openclaw/plugin-sdk/*（插件开发 SDK）相互独立。

两层架构

1. 低层：从 Gateway 协议 schema 自动生成的客户端
2. 高层：封装 OpenClaw、Agent、Session、Run、Task、Artifact、Approval、Environment 等对象

命名空间设计

oc.agents.list();
oc.sessions.create(...);
oc.runs.create(...);
oc.tasks.list({ status: "running" });
oc.artifacts.list({ runId });
oc.approvals.respond(approvalId, ...);
oc.environments.list();

高层封装示例：

const run = await agent.run(inputOrParams);
await run.wait();
for await (const event of run.events()) { ... }

事件类型

事件	含义
run.created/started/completed/failed	Run 生命周期
assistant.delta/message	助手输出
tool.call.started/completed/failed	工具调用
approval.requested/resolved	审批流程
artifact.created/updated	产物变更
session.compacted	会话压缩

Token 权限范围

Scope	权限
agent.run	启动 Run
session.write	创建/发送/压缩会话
approval.respond	审批/拒绝请求
artifacts.read	列出/下载产物
admin	管理操作

推荐包结构

包名	用途
@openclaw/sdk	公共高层 SDK + 低层 Gateway 客户端
@openclaw/sdk-react	React hooks（可选）
@openclaw/sdk-testing	测试辅助工具

相关页面

• ref-rpc
• docs/concepts/concept-agent-loop