OpenClaw App SDK 完整度评估指南：六维能力面与外部应用开发工作流审查框架

OpenClaw App SDK 完整度评估指南：六维能力面与外部应用开发工作流审查框架

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

OpenClaw 不仅以 Gateway、插件与多平台 App 连接用户，还向外部应用开发者暴露了一组用于连接 Gateway、驱动 Agent 运行、订阅事件并处理审批的客户端 API。这类能力属于仓库成熟度模型中一个独立的评审面——openclaw-app-sdk。本文围绕该面的完整度（Completeness）评估框架展开：先解释这套评分规则在整个 claw-score 工作流中的位置与运行前提，再逐维拆解它所定义的六大能力面，最后结合packages/sdk的真实实现与测试，说明每个能力面“完整”意味着什么、当前仓库的证据边界在哪里，以及评审时应警惕的完整性缺口。

读完本文，你将掌握：openclaw-app-sdk面完整的类目范围（Client API、Gateway Access、Agent Conversations、Events and Approvals、Resource Helpers、Compatibility），每一类目对应的 taxonomy 特征与 SDK 源码/测试证据，以及如何用 rubric 中的“表面专属评分问题”来判断一个外部 App 开发者能否真正端到端完成工作流。

背景：rubric 在 claw-score 工作流中的定位

本仓库用taxonomy.yaml维护全部成熟度评审面（surface）、级别与特征，其中app-sdk面被定义为family: core、level_code: M2（Alpha），并显式挂接了完整性评审指引：

- id: app-sdk name: OpenClaw App SDK ... level_code: M2 rationale: OpenClaw App SDK is a distinct external app contract separate from Gateway runtime and Plugin SDK. ... completeness_instructions: references/completeness/openclaw-app-sdk.md

（见 taxonomy.yaml。）也就是说，本文剖析的文档正是taxonomy.yaml中该面引用的completeness_instructions文件——评审者给它打分前必须遵循的“表面专属评分规则”。

它嵌入在 claw-score 技能的工作流中：技能规定“为某个面打分”时，先读taxonomy.yaml中的该面定义，再读.agents/skills/claw-score/references/completeness/下对应的 rubric 文件，然后从文档、源码、测试与 QA 场景元数据中收集公开证据，最后只依据qa/maturity-scores.yaml更新 Quality、Completeness 与 LTS 的评审状态。关键约束是：不得手工修改生成的 Markdown 分数，所有分数数据必须落在qa/maturity-scores.yaml中。

由此可知，这份 rubric 不是给普通 SDK 使用者的教程，而是给“成熟度评审者”的能力清单与判断锚点；但它的价值远超评分本身——它精确刻画了 OpenClaw 作为“外部应用平台”应当交付的完整客户端契约。

表面专属规则：完整度不是“实现质量”

claw-score 的默认完整度流程（见 SKILL.md）将 Completeness 定义为“面向该面预期使用者的完整可见工作流”，并明确三条纪律：

• 不要因为测试稀疏而降低 Completeness（那是 Coverage 的职责）；
• 不要因为实现脆弱而降低 Completeness（那是 Quality 的职责）；
• 完整度只回答一个问题：预期的操作者工作流有多少真正交付了？

openclaw-app-sdk的 rubric 则把默认流程做了一次表面专属（surface-specific）收敛。它的指导核心可概括为三点：

1. 完整度=外部 App 开发者从“连接”到“Agent 运行、会话、事件、审批、资源、兼容性、操作错误处理”的端到端体验，而不是 Gateway 内部协议片段的罗列。
2. 一个“完整”的 SDK 类目，应通过类型化、有文档、可复用的客户端 API 暴露能力——而不是要求调用方手工拼接低层 Gateway 帧，或依赖内部包的形状。
3. “手工构造 Gateway 帧”或“依赖内部包形状”本身就是重大的完整性缺口（material completeness gap）。

这条规则意味着评审者在打分时应以“开发者是否能用公开 API 完成整个工作流”为标尺，而不是检查底层 RPC 是否实现了某一方法。下文每一个能力面都会沿用这把标尺。

六大能力面详解

rubric 将openclaw-app-sdk面切分为六个类目。下面逐一说明其评估范围、对应 taxonomy 特征，以及当前仓库中可交叉印证的源码/测试证据。

1. Client API：入口、命名空间布局与边界

评估范围：SDK 入口点（entrypoints）、命名空间布局、包划分（package split，含核心 SDK 与可能的 React/测试辅助包边界）、App/插件边界。

这一能力面在 taxonomy.yaml 中被展开为四个特征：SDK entrypoints（外部 App 的公共包导入与辅助对象）、Namespace layout（如 agents/sessions 等高层与低层命名空间）、Package split、App/plugin boundary（外部 App 集成与进程内插件编写之间的清晰边界）。

源码佐证非常直接。packages/sdk/src/index.ts 就是 SDK 的单一公共入口，它从client.js再导出根客户端与全部命名空间：

• 根客户端OpenClaw，以及Agent、Run、Session三个句柄类；
• 命名空间：AgentsNamespace、RunsNamespace、SessionsNamespace、TasksNamespace、ModelsNamespace、ToolsNamespace、ArtifactsNamespace、ApprovalsNamespace、EnvironmentsNamespace；
• 事件侧导出EventHub、isGatewayEvent、normalizeGatewayEvent；
• 传输层导出GatewayClientTransport、isConnectableTransport与OpenClawTransport类型。

而 client.ts 中的OpenClaw构造函数将这些命名空间一次性装配成实例属性。App/插件边界则体现在仓库的包划分本身：外部 App 使用的是@openclaw/sdk（package.json），而进程内插件编写走的是另一套packages/plugin-sdk——这与 taxonomy 的rationale（“App SDK 是独立于 Gateway runtime 和 Plugin SDK 的外部 App 契约”）一致。

评审时值得提问的问题：当前仓库可见的是“核心 SDK 单包”形态；taxonomy 期待的Package split中“React helpers 与 testing 包边界”在当前可见源码中是否有独立交付物？若没有，则需要判断这是否构成该特征下的完整性缺口，而不是直接默认低分——需回到证据判断。

2. Gateway Access：连接、令牌与自定义传输

评估范围：Gateway 连接、URL/令牌配置、自动 Gateway、自定义传输、作用域与脱敏（scopes/redaction）。

对应 taxonomy 特征（taxonomy.yaml）：显式 Gateway 连接的 SDK 构造、URL/token/auth 输入、受支持环境的自动 Gateway 发现、非默认客户端环境的传输注入，以及令牌作用域、密钥转发默认值与脱敏边界。

源码中的连接配置集中在OpenClawOptions类型（client.ts）：

export type OpenClawOptions = { gateway?: "auto" | (string & {}); url?: string; token?: string; password?: string; requestTimeoutMs?: number; transport?: OpenClawTransport; };

resolveGatewayUrl（client.ts）的逻辑是：优先取options.url；否则若gateway提供了非"auto"的具体地址则使用该地址；若为"auto"则返回undefined。构造函数中，当未显式注入transport时，会用url/token/password/requestTimeoutMs构造默认的GatewayClientTransport（client.ts），因此传输可注入与URL/令牌可配置这两点都有明确的实现证据。

需要留意的边界：当前实现中gateway: "auto"并不会触发额外的“自动发现”分支，而是回落为交给默认 transport 处理；Scopes and redaction（令牌作用域与脱敏边界）在 taxonomy 中是独立特征，但当前OpenClawOptions中并没有暴露 scopes 的显式字段。这两点应作为评审该能力面完整度时重点核对的潜在分支，而非想当然的既定能力。

3. Agent Conversations：句柄、运行与会话控制

评估范围：Agent 句柄、Agent 运行、运行结果、会话创建、会话发送、会话控制。

对应 taxonomy 特征（taxonomy.yaml）非常详尽：Agent 句柄的创建与查找、带流式运行事件的 Agent 执行路径、运行结果信封（wait 语义、超时处理与结果归一化）、可复用会话句柄创建、外部 App 的会话转录交互，以及 patch/abort/compact 等会话操作。

源码层面，Agent句柄类（client.ts）提供run(input)与identity()；run()最终委托给RunsNamespace.create()。Run句柄类（client.ts）则聚合了三个核心操作：

• events(filter?)：订阅该 run 的归一化事件流；
• wait({ timeoutMs })：向 Gateway 发起agent.wait并将超时/取消语义归一化为RunResult.status；
• cancel()：通过sessions.abort中止运行。

等待语义的归一化是本能力面最有技术含量的部分：runStatusFromWaitPayload（client.ts）会综合 payload 中的status、stopReason、pendingError、timeoutPhase、endedAt等字段，而不是信任单一状态字段，把结果归类为completed、cancelled、timed_out、accepted或failed。这正是 rubric 强调的“客户端 API 将 Gateway 行为封装为稳定可复用语义”的典型体现——开发者不需要自己解析底层等待帧。

从代码结构推断，会话创建/发送/控制等操作分布在SessionsNamespace中，而仓库中的端到端测试（如 app-sdk-external-boundary.e2e.test.ts、index.e2e.test.ts）覆盖了外部边界行为，可作为评审该类目“工作流可走通”的证据来源。

4. Events and Approvals：事件流、信封、重放游标与审批

评估范围：事件流、事件信封、重放游标、审批回调、问题（questions）。

对应 taxonomy 特征（taxonomy.yaml）：App 级与 run 级事件流的订阅、面向外部客户端的稳定事件信封、可重放的事件族与稳定游标、面向外部 App 的一等公民审批处理，以及与审批流并行的 question 处理。

事件架构的实现核心是 event-hub.ts 的EventHub，它提供带replayLimit的广播与订阅；而 normalize.ts 的normalizeGatewayEvent负责把低层 Gateway 事件转换为OpenClawEvent稳定信封。OpenClaw客户端暴露三层事件 API（client.ts）：

• events(filter?)：归一化的 App 级事件流；
• runEvents(runId, filter?)：run 级事件流；
• rawEvents(filter?)：透传 Gateway 原始事件（供高级场景使用）。

run 事件流尤其值得一提：iterateRunEvents（client.ts）会先回放内存中的replayByRunId快照（每 run 最多 500 条、全客户端最多 100 个 run、归一化后最多 2000 条，见 client.ts），再无缝切换到 live 流，并基于事件id去重——这就是“带重放游标语义的事件订阅”的实现证据。同时它会把聊天投影事件（raw.event === "chat"的 delta/final）归一化为assistant.delta/run.completed，避免外部客户端同时看到“chat 投影”与“规范化 run 事件”两份重复语义（client.ts）。

审批相关能力在客户端类目中对应ApprovalsNamespace与根客户端上的readonly approvals（client.ts），并以ApprovalDecisionParams、ApprovalMode等类型导出。评审时需要追问：审批是否以“回调/一等 API”形式对外，开发者能否不接触协议细节完成审批决策与 question 交互。

5. Resource Helpers：模型、ToolSpace、工件、任务与环境

评估范围：models、ToolSpace、工件（artifacts）、任务（tasks）、环境（environments）等资源辅助层。

对应 taxonomy 特征（taxonomy.yaml）：类型化的模型发现辅助、面向外部 App 的工具发现与调用抽象（ToolSpace）、工件列表/获取/下载与构建的精确覆盖、围绕 Gateway 任务 API 的 SDK 辅助、托管环境提供者的生命周期与元数据。

源码侧，这些能力以命名空间形式存在于OpenClaw上：models、tools、artifacts、tasks、environments（client.ts）。几个值得写进评审笔记的实现细节：

• 工具“有效配置”需要会话作用域：hasToolsEffectiveSessionKey/requireToolsEffectiveSessionKey（client.ts）要求oc.tools.effective必须携带sessionKey，否则直接抛错——说明 tools 辅助层不是凭空查询，而是绑定会话上下文。
• 工件查询需要作用域：requireArtifactQueryScope（client.ts）强制工件列表/获取必须给定sessionKey、runId或taskId三者之一，否则抛 “requires one of sessionKey, runId, or taskId”。对应的ArtifactsListResult、ArtifactsGetResult、ArtifactsDownloadResult等类型在 types.ts 中统一定义。
• 模型引用解析辅助splitModelRef（client.ts）支持把"provider/model"形式的引用拆成独立的 provider 与 model 字段——这构成了 “typed model discovery helpers” 的底层支撑。
• 组合资源场景由 app-sdk-composed-resources.e2e.test.ts 端到端验证，是评审“跨命名空间组合工作流”时可引用的测试证据。

6. Compatibility：生成客户端、封装层与显式不支持

评估范围：生成客户端、人体工学封装（ergonomic wrappers）、不支持调用、schema 对齐、公共包契约。

对应 taxonomy 特征（taxonomy.yaml）：基于 Gateway schema 的客户端生成、在生成传输契约之上手写的封装层、对不支持的环境变更与未来 per-run 覆盖给出显式错误、SDK 行为与 Gateway schema 保持对齐，以及被显式跟踪的包发布与可复用客户端预期。

源码中最有说服力的“显式不支持”证据是assertNoUnsupportedRunOptions（client.ts）：当调用方在AgentRunParams中传入workspace、runtime、environment或approvals这些当前 Gateway 尚未支持的 per-run SDK 选项时，SDK 不会静默忽略，而是抛出明确错误：

OpenClaw Gateway does not support per-run SDK options yet: <option>

同时buildAgentParams（client.ts）会在发起 run 前对参数做规整：模型引用拆分、timeoutMs归一化为秒、自动生成幂等键（idempotencyKey ?? randomUUID()）等。另有通用的unsupportedGatewayApi(api)（client.ts）用于对尚未支持的 Gateway API 抛出一致错误。这些都属于“人体工学封装层 + schema 对齐 + 不支持调用显式化”的成对实现——封装方在语义上承担了 Gateway 协议与外部调用方之间的兼容层职责。

评审提示：schema 对齐的更多证据散落在协议/归一化包中（SDK 依赖@openclaw/gateway-protocol与@openclaw/normalization-core，见 package.json），外部边界的行为契约则由app-sdk-external-boundary.e2e.test.ts固化。

评分问题清单：逐类目核查的五问法

rubric 为每个类目定义了五条“表面专属评分问题”。这些问题是评审时逐类目自问的判断清单，也是外部 App 平台完整性的通用检查表：

1. 外部 App 开发者能否只用公共 SDK API 完成该类目的完整工作流？——判断时回到本文各能力面的源码证据：例如 Agent 运行要确认Agent.run/RunsNamespace.create是否足够，还是必须退回request("agent.*")手拼 RPC。
2. taxonomy 特征是否以稳定的客户端契约呈现，而非仅有协议级片段？——例如事件订阅若只暴露rawEvents而没有归一化信封与去重重放，则视为协议片段而不是稳定契约。
3. setup、认证、流式、结果处理、错误行为与兼容性预期是否都有文档？——这要求评审者核对公开文档中这些环节是否有对应描述。
4. 浏览器、Node、React、测试与自定义传输变体在类目期望它们出现的地方是否被覆盖？——对应 taxonomy 中 “Package split（React helpers、testing 包）”等特征。
5. 已知缺口是否导致外部 App 的主要能力分支缺失？——例如自动 Gateway 发现、per-run approvals 覆盖等。

需要再次强调的是（见 SKILL.md）：当表面专属指令与默认流程发生出入时，以表面专属指令为准，并在打分理由中体现这一选择。对openclaw-app-sdk而言，意味着“开发者能否用公开 SDK 完成端到端工作流”永远优先于“Gateway 内部是否实现了该 RPC”。

当前状态与可追踪的缺口示例

结合 docs/maturity/taxonomy.md 渲染的成熟度面板，OpenClaw App SDK当前处于M2 / Alpha层级，6 个面积区、总体完成度 53%；而 taxonomy.yaml 记录该面最近一次评分于 2026-06-01 由 codex 完成，说明该面仍被官方持续跟踪为“可真实使用的@openclaw/sdk路径，但在公共打包、自动发现、审批、辅助层与兼容性方面仍存在缺口”（见该 surface 的 rationale）。

在此基础上，若以本文的 rubric 重审，可得到以下可操作的缺口观察清单（均基于当前仓库可见证据，供评审者复核）：

• Gateway Access：OpenClawOptions目前暴露 url/token/password/transport 与gateway: "auto"占位，但未看到显式的 scopes 字段或真正的自动发现逻辑；“Scopes and redaction” 特征有待更明确的客户端契约证据。
• Resource Helpers：artifacts 与 tools.effective 都强制要求会话级作用域，这类限制在有文档说明的前提下是合理设计，但需要确认其已作为“预期错误行为”公开说明，否则对开发者而言是隐式约束。
• Compatibility：per-run 的 workspace/runtime/environment/approvals 覆盖被显式判定为“尚不支持”，这是封装层诚实暴露边界的正面案例；但同时也意味着“未来 per-run overrides”仍是该面的已知开放分支。
• 文档锚点：taxonomy 中多处将该面文档锚定到docs/concepts/openclaw-sdk.md与docs/reference/openclaw-sdk-api-design.md（见各类目docs列表），但在当前仓库中未检索到这两个路径对应的文件；从完整度视角，这说明“setup、认证、错误行为与兼容性预期均有文档”这一评分问题尚未被完全满足，属于需要优先补强的证据缺口。

附：完整度分带参考

打分时，将上述核查结果映射到 SKILL.md 定义的分带即可得出该类目分数：

• Clawesome（95-100）：预期工作流、变体与恢复分支齐备，仅剩少量打磨性缺口；
• Stable（80-95）：预期工作流大体齐备，仅有有限缺失分支；
• Beta（70-80）：主工作流存在，但有意义的分支或恢复路径仍然缺失；
• Alpha（50-70）：仅具备部分能力集，用户能完成部分核心任务但无法走通完整预期工作流；
• Experimental（0-50）：只暴露了预期能力的碎片。

对openclaw-app-sdk这一面的每个类目，评审者应把“外部 App 开发者端到端工作流”作为不变的判据，用本文六大能力面的源码/测试证据逐条作答，再把结果写入qa/maturity-scores.yaml——这样得出的完整度分数才既忠实于 rubric，又可被后续的验证与回归追踪。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw