企业官网建设流程全解析

Cherry Studio 集成 OpenClaw：以 Code Mate Skill 驱动本地 Agent 的非交互式调用指南

【免费下载链接】cherry-studio🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio

导读

resources/code-cli-skills/code-mate-openclaw/SKILL.md是 Cherry Studio 为 Code Mate 功能预置的技能（Skill）模板，它定义了一套将用户请求委托给本地 OpenClaw 主 Agent 的规范流程：通过一条非交互式的openclaw agent命令完成有界任务，并以结构化 JSON 作为返回协议。本文以此 Skill 文档为骨架，结合 Cherry Studio 仓库中 CodeCliService、OpenClawService 与 codeCliTools 预设 的源码实现，完整讲解该 Skill 的调用方式、鉴权与权限边界、错误处理策略，以及在 Cherry Studio 中它如何被安装、同步和驱动 OpenClaw 网关。读完本文，你将掌握 OpenClaw Skill 的完整使用规范，并理解其与 Cherry Studio 底层服务之间的配合关系。

Skill 的定位与触发条件

Skill 文档的开头以 YAML front-matter 声明了该技能的身份：

name: code-mate-openclaw description: Runs a local OpenClaw agent non-interactively and returns its structured response. Use when the user asks to delegate a bounded task to the OpenClaw main agent.

两个字段共同决定该 Skill 何时被选用：

• name：技能唯一标识，即code-mate-openclaw；
• description：供 Agent/LLM 语义匹配的触发描述，明确指出适用场景是“用户要求将一个有界（bounded）任务委托给 OpenClaw 主 Agent”。

与仓库中resources/code-cli-skills/目录下其他 Code Mate 技能（如code-mate-claude-code、code-mate-codex、code-mate-pi等）并列，该 Skill 是 Cherry Studio 的 Code Mate 功能为 OpenClaw 定制的调用契约。从源码看，codeCliTools.ts 中为 OpenClaw 定义了完整预设：

defineCodeCliTool({ id: CodeCli.OPENCLAW, executable: 'openclaw', skillFolderName: 'code-mate-openclaw', packageName: 'openclaw', install: 'npm' })

即：可执行文件名为openclaw，通过 npm 安装（install: 'npm'，包名openclaw），Skill 文件夹名正是本文主题所在的code-mate-openclaw。这说明 Skill 模板与 CLI 工具预设是一一对应的：安装/发现 OpenClaw 可执行文件后，其 Skill 才会被安装与启用。

Run：非交互式调用规范

Skill 文档的 "Run" 一节给出了最核心的执行步骤，共 3 步，本小节逐条展开并结合源码佐证。

第 1 步：固定工作目录与有限超时

Set the Bash working directory to the exact directory the user authorized and set a finite outer timeout, normally 11 minutes.

执行前必须：

• 将 Shell 工作目录设置为用户明确授权的目录（不能擅自换成其他目录）；
• 设置一个有限的整体超时，正常情况为 11 分钟。

11 分钟的建议值并非随意：它对应命令内部--timeout 600（10 分钟）再加上进程启动、JSON 解析等固定开销余量，确保外层超时始终大于内层超时，避免外层的“假超时”杀死一个仍在正常工作的内部任务。从 Cherry Studio 源码可见类似的超时策略——OpenClawService 中定义OPENCLAW_COMMAND_TIMEOUT_MS = 10000作为预检命令超时，并通过setTimeout+proc.kill('SIGKILL')强制终止超时进程。这印证了“外层必须兜底、内层优先自主完成”的分层超时设计是仓库内的一致惯例。

第 2 步：可用性预检

Check availability withcommand -v openclaw. If it is missing, stop and ask the user to install OpenClaw in Code Mate.

用command -v openclaw检查可执行文件是否存在于 PATH。若缺失，不要自行安装或绕过，而是停下并请用户在 Code Mate 中安装 OpenClaw。

仓库侧对应的能力探测逻辑在 resolveOpenClawRuntime：它通过BinaryManager.getToolSnapshots(['openclaw'])获取工具快照，若availability.source === 'none'则抛出OpenClaw binary not found. Please install OpenClaw first.，并且会根据来源决定环境变量：系统安装（source === 'system'）使用原始 Shell 环境，否则使用 BinaryManager 托管的环境。可见“先探测、缺失即停下”的规范在 Skill 层（command -v）与主进程服务层（BinaryManager 快照）是一致的。

第 3 步：单次运行本地主 Agent

Skill 文档给出的核心命令为：

openclaw agent --local --agent main --message "<prompt>" --json --timeout 600

参数逐一说明：

这与 codeCliTools 测试 中固化的 OpenClaw 调用模板完全一致：

[CodeCli.OPENCLAW]: 'openclaw agent --local --agent main --message "<prompt>" --json --timeout 600'

也就是说，该命令模板被仓库测试锁定为 OpenClaw 工具预设的“标准动作”，Skill 文档与测试互为印证。

解析规则：进程退出码不等于成功

Skill 文档特别强调一条容易被忽略的关键规则：

Parse the JSON payload even when the process exits zero: OpenClaw can encode failure in a successful process exit. Report payload errors and timeouts as failures.

即使进程以 0 退出，也必须解析 JSON 载荷——OpenClaw 可能在“成功退出”的进程里编码失败结果。因此：

• 成功 = 进程正常结束且JSON 载荷报告成功；
• 载荷报错、载荷解析失败、超时，一律视为失败；
• 严禁启动 onboarding、交互式 TUI 或登录流程（即--local --agent main的非交互形态是强制约束）。

仓库的 parseValidationResult 展示了同类“退出码 + JSON 双通道校验”的工程实践：它要求report.valid必须为布尔值、issues/warnings必须符合结构，并且(valid && exitCode !== 0) || (!valid && exitCode !== 1)时直接判定失败——即退出码与 JSON 内容必须互相印证，任何单方面“成功”都不可信。这与 Skill 中“退出 0 也需解析 JSON”的原则属于同一设计哲学。

鉴权与权限边界

Skill 文档的 "Authentication And Permissions" 一节定义了安全红线，分为两个方面。

凭据处理：零接触原则

If OpenClaw reports missing onboarding, provider, model, or credentials, stop and ask the user to configure OpenClaw in Code Mate. Never request, read, print, or copy credentials.

• 若 OpenClaw 报告缺失 onboarding、provider、model 或凭据，立即停止，请用户在 Code Mate 中完成 OpenClaw 配置；
• 绝对不得请求、读取、打印或复制任何凭据——即使是“帮忙查看配置”也不被允许。

主进程侧同样贯彻了凭据最小化：OpenClawService 的配置同步（syncProviderConfig，OpenClawService.ts）会把 Cherry Studio 的 Provider/模型映射写入openclaw.json，且配置文件以0o600权限原子写入（atomicWriteFile），并对诊断信息调用 sanitizeOpenClawDiagnostic 进行密钥脱敏（redactSecretText）后截断展示。这些实现细节表明：凭据只应存在于受保护的本机配置中，任何面向 Agent/用户的输出都必须脱敏。

作用域限制：默认只读

The local agent can invoke configured tools. Keep the prompt read-only by default and do not ask it to mutate files or external systems unless the user explicitly requested workspace changes or that external effect. Limit it to the selected working directory.

• 本地 Agent 可以调用已配置的工具，因此提示词默认只读；
• 除非用户明确要求修改工作区或产生外部影响，否则不得让 Agent 改动文件或外部系统；
• 一切操作被限制在用户授权的选定工作目录内。

这与第 1 步“工作目录必须是用户授权目录”的要求前后呼应，构成完整的沙箱式边界：目录 + 只读 + 无外部副作用。Skill 文档最后给出的示例正是这一原则的落地：

Example: ask the main agent to explain a module without changing it, then accept the response only when the JSON payload reports success.

即“解释模块、不改动模块”——这是默认的只读调用形态。

错误与失败的处理策略

综合 Skill 全文，失败处理遵循一套明确的判定与上报路径：

1. 二进制缺失（command -v openclaw失败）→ 停下，请用户在 Code Mate 安装；
2. 配置缺失（onboarding/provider/model/凭据缺失）→ 停下，请用户在 Code Mate 配置，不读取凭据；
3. 执行失败（进程异常、内部超时、JSON 载荷报错）→ 按失败上报，不将退出码 0 视为成功；
4. 流程越界（TUI、onboarding、登录、写操作）→ 一律禁止，防止把有界任务变成不受控的交互式会话。

仓库侧为这类错误提供了分层兜底：OpenClawService通过GatewayStatus（stopped | starting | running | error，见 OpenClawService.ts）对外暴露网关状态，启动网关时先做配置校验（assertConfigValid）、端口占用检查、健康探测（/healthz期望{"ok":true,"status":"live"}），任一环节失败都会收敛到明确的错误消息。Skill 层与主进程服务层共同构成“命令级校验 + 服务级守卫”的双保险。

在 Cherry Studio 中的生命周期：Skill 如何被安装与同步

该 Skill 并非静态文件，而是随 OpenClaw 可执行文件的安装/卸载被动态管理的。关键调用链如下：

• 内置 Skill 模板位于 pathRegistry.ts 注册的feature.code_cli.skills.builtin路径（即resources/code-cli-skills）；
• CodeCliService.installCli 在安装 CLI 后调用installCliSkill(preset)，将code-mate-openclaw目录通过skillService.syncBuiltinSkill(...)同步为已安装技能；
• removeCli与reconcileCliSkill（CodeCliService.ts）在工具被卸载或发现缺失时调用skillService.uninstallBuiltinSkill反向清理；
• 应用启动进入onAllReady阶段时执行reconcileCliSkills()（CodeCliService.ts），保证 Skill 与底层二进制状态始终一致。

也就是说：用户一旦在 Code Mate 中安装了 OpenClaw，code-mate-openclaw/SKILL.md就会自动成为可用技能；卸载 OpenClaw 后该技能随之移除。Skill 文档中“请用户在 Code Mate 中安装/配置 OpenClaw”的措辞，正对应这条自动化链路。

与之配套的是模型与网关配置的打通：OpenClawService.syncConfig（OpenClawService.ts）会把用户在 Cherry Studio 中选择的 Provider、主模型、API Key、上下文窗口、maxTokens、reasoning 与价格信息写入 OpenClaw 的openclaw.json（含models.providers.cherry-<id>命名空间、agents.defaults.model.primary、gateway.mode = 'local'与自动生成的鉴权 token），随后startGateway以openclaw gateway run --force启动本地网关。Skill 中的--local模式正是运行在这一被同步配置好的本地运行时之上。

小结

code-mate-openclawSkill 是 Cherry Studio Code Mate 与 OpenClaw 之间的一份“最小调用契约”，其精髓可浓缩为四点：

1. 非交互：--local --agent main --message "<prompt>" --json --timeout 600单次运行，禁止 TUI/onboarding/登录；
2. 双通道判定：进程退出码与 JSON 载荷必须同时为成功，才可采信结果；
3. 安全边界：授权目录内默认只读，凭据零接触，配置缺失即停止并引导用户在 Code Mate 中配置；
4. 自动化装配：Skill 由 CodeCliService 随 OpenClaw 二进制的安装/卸载自动同步，配置由 OpenClawService 自动写入并校验。

对希望在 Cherry Studio 中通过 Code Mate 使用 OpenClaw 的开发者，本文配套源码入口包括：Skill 模板、CLI 工具预设、Skill 安装与回收、OpenClaw 网关与配置服务，以及预设测试中固化的调用模板。

【免费下载链接】cherry-studio🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio