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: M2Alpha并显式挂接了完整性评审指引- 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收敛。它的指导核心可概括为三点完整度外部 App 开发者从“连接”到“Agent 运行、会话、事件、审批、资源、兼容性、操作错误处理”的端到端体验而不是 Gateway 内部协议片段的罗列。一个“完整”的 SDK 类目应通过类型化、有文档、可复用的客户端 API 暴露能力——而不是要求调用方手工拼接低层 Gateway 帧或依赖内部包的形状。“手工构造 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/sdkpackage.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.tsexport type OpenClawOptions { gateway?: auto | (string {}); url?: string; token?: string; password?: string; requestTimeoutMs?: number; transport?: OpenClawTransport; };resolveGatewayUrlclient.ts的逻辑是优先取options.url否则若gateway提供了非auto的具体地址则使用该地址若为auto则返回undefined。构造函数中当未显式注入transport时会用url/token/password/requestTimeoutMs构造默认的GatewayClientTransportclient.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.statuscancel()通过sessions.abort中止运行。等待语义的归一化是本能力面最有技术含量的部分runStatusFromWaitPayloadclient.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.yamlApp 级与 run 级事件流的订阅、面向外部客户端的稳定事件信封、可重放的事件族与稳定游标、面向外部 App 的一等公民审批处理以及与审批流并行的 question 处理。事件架构的实现核心是 event-hub.ts 的EventHub它提供带replayLimit的广播与订阅而 normalize.ts 的normalizeGatewayEvent负责把低层 Gateway 事件转换为OpenClawEvent稳定信封。OpenClaw客户端暴露三层事件 APIclient.tsevents(filter?)归一化的 App 级事件流runEvents(runId, filter?)run 级事件流rawEvents(filter?)透传 Gateway 原始事件供高级场景使用。run 事件流尤其值得一提iterateRunEventsclient.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 approvalsclient.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、environmentsclient.ts。几个值得写进评审笔记的实现细节工具“有效配置”需要会话作用域hasToolsEffectiveSessionKey/requireToolsEffectiveSessionKeyclient.ts要求oc.tools.effective必须携带sessionKey否则直接抛错——说明 tools 辅助层不是凭空查询而是绑定会话上下文。工件查询需要作用域requireArtifactQueryScopeclient.ts强制工件列表/获取必须给定sessionKey、runId或taskId三者之一否则抛 “requires one of sessionKey, runId, or taskId”。对应的ArtifactsListResult、ArtifactsGetResult、ArtifactsDownloadResult等类型在 types.ts 中统一定义。模型引用解析辅助splitModelRefclient.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 保持对齐以及被显式跟踪的包发布与可复用客户端预期。源码中最有说服力的“显式不支持”证据是assertNoUnsupportedRunOptionsclient.ts当调用方在AgentRunParams中传入workspace、runtime、environment或approvals这些当前 Gateway 尚未支持的 per-run SDK 选项时SDK 不会静默忽略而是抛出明确错误OpenClaw Gateway does not support per-run SDK options yet: option同时buildAgentParamsclient.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 平台完整性的通用检查表外部 App 开发者能否只用公共 SDK API 完成该类目的完整工作流——判断时回到本文各能力面的源码证据例如 Agent 运行要确认Agent.run/RunsNamespace.create是否足够还是必须退回request(agent.*)手拼 RPC。taxonomy 特征是否以稳定的客户端契约呈现而非仅有协议级片段——例如事件订阅若只暴露rawEvents而没有归一化信封与去重重放则视为协议片段而不是稳定契约。setup、认证、流式、结果处理、错误行为与兼容性预期是否都有文档——这要求评审者核对公开文档中这些环节是否有对应描述。浏览器、Node、React、测试与自定义传输变体在类目期望它们出现的地方是否被覆盖——对应 taxonomy 中 “Package splitReact helpers、testing 包”等特征。已知缺口是否导致外部 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 AccessOpenClawOptions目前暴露 url/token/password/transport 与gateway: auto占位但未看到显式的 scopes 字段或真正的自动发现逻辑“Scopes and redaction” 特征有待更明确的客户端契约证据。Resource Helpersartifacts 与 tools.effective 都强制要求会话级作用域这类限制在有文档说明的前提下是合理设计但需要确认其已作为“预期错误行为”公开说明否则对开发者而言是隐式约束。Compatibilityper-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 定义的分带即可得出该类目分数Clawesome95-100预期工作流、变体与恢复分支齐备仅剩少量打磨性缺口Stable80-95预期工作流大体齐备仅有有限缺失分支Beta70-80主工作流存在但有意义的分支或恢复路径仍然缺失Alpha50-70仅具备部分能力集用户能完成部分核心任务但无法走通完整预期工作流Experimental0-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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: M2Alpha并显式挂接了完整性评审指引- 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收敛。它的指导核心可概括为三点完整度外部 App 开发者从“连接”到“Agent 运行、会话、事件、审批、资源、兼容性、操作错误处理”的端到端体验而不是 Gateway 内部协议片段的罗列。一个“完整”的 SDK 类目应通过类型化、有文档、可复用的客户端 API 暴露能力——而不是要求调用方手工拼接低层 Gateway 帧或依赖内部包的形状。“手工构造 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/sdkpackage.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.tsexport type OpenClawOptions { gateway?: auto | (string {}); url?: string; token?: string; password?: string; requestTimeoutMs?: number; transport?: OpenClawTransport; };resolveGatewayUrlclient.ts的逻辑是优先取options.url否则若gateway提供了非auto的具体地址则使用该地址若为auto则返回undefined。构造函数中当未显式注入transport时会用url/token/password/requestTimeoutMs构造默认的GatewayClientTransportclient.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.statuscancel()通过sessions.abort中止运行。等待语义的归一化是本能力面最有技术含量的部分runStatusFromWaitPayloadclient.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.yamlApp 级与 run 级事件流的订阅、面向外部客户端的稳定事件信封、可重放的事件族与稳定游标、面向外部 App 的一等公民审批处理以及与审批流并行的 question 处理。事件架构的实现核心是 event-hub.ts 的EventHub它提供带replayLimit的广播与订阅而 normalize.ts 的normalizeGatewayEvent负责把低层 Gateway 事件转换为OpenClawEvent稳定信封。OpenClaw客户端暴露三层事件 APIclient.tsevents(filter?)归一化的 App 级事件流runEvents(runId, filter?)run 级事件流rawEvents(filter?)透传 Gateway 原始事件供高级场景使用。run 事件流尤其值得一提iterateRunEventsclient.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 approvalsclient.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、environmentsclient.ts。几个值得写进评审笔记的实现细节工具“有效配置”需要会话作用域hasToolsEffectiveSessionKey/requireToolsEffectiveSessionKeyclient.ts要求oc.tools.effective必须携带sessionKey否则直接抛错——说明 tools 辅助层不是凭空查询而是绑定会话上下文。工件查询需要作用域requireArtifactQueryScopeclient.ts强制工件列表/获取必须给定sessionKey、runId或taskId三者之一否则抛 “requires one of sessionKey, runId, or taskId”。对应的ArtifactsListResult、ArtifactsGetResult、ArtifactsDownloadResult等类型在 types.ts 中统一定义。模型引用解析辅助splitModelRefclient.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 保持对齐以及被显式跟踪的包发布与可复用客户端预期。源码中最有说服力的“显式不支持”证据是assertNoUnsupportedRunOptionsclient.ts当调用方在AgentRunParams中传入workspace、runtime、environment或approvals这些当前 Gateway 尚未支持的 per-run SDK 选项时SDK 不会静默忽略而是抛出明确错误OpenClaw Gateway does not support per-run SDK options yet: option同时buildAgentParamsclient.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 平台完整性的通用检查表外部 App 开发者能否只用公共 SDK API 完成该类目的完整工作流——判断时回到本文各能力面的源码证据例如 Agent 运行要确认Agent.run/RunsNamespace.create是否足够还是必须退回request(agent.*)手拼 RPC。taxonomy 特征是否以稳定的客户端契约呈现而非仅有协议级片段——例如事件订阅若只暴露rawEvents而没有归一化信封与去重重放则视为协议片段而不是稳定契约。setup、认证、流式、结果处理、错误行为与兼容性预期是否都有文档——这要求评审者核对公开文档中这些环节是否有对应描述。浏览器、Node、React、测试与自定义传输变体在类目期望它们出现的地方是否被覆盖——对应 taxonomy 中 “Package splitReact helpers、testing 包”等特征。已知缺口是否导致外部 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 AccessOpenClawOptions目前暴露 url/token/password/transport 与gateway: auto占位但未看到显式的 scopes 字段或真正的自动发现逻辑“Scopes and redaction” 特征有待更明确的客户端契约证据。Resource Helpersartifacts 与 tools.effective 都强制要求会话级作用域这类限制在有文档说明的前提下是合理设计但需要确认其已作为“预期错误行为”公开说明否则对开发者而言是隐式约束。Compatibilityper-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 定义的分带即可得出该类目分数Clawesome95-100预期工作流、变体与恢复分支齐备仅剩少量打磨性缺口Stable80-95预期工作流大体齐备仅有有限缺失分支Beta70-80主工作流存在但有意义的分支或恢复路径仍然缺失Alpha50-70仅具备部分能力集用户能完成部分核心任务但无法走通完整预期工作流Experimental0-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考