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-openclawdescription供 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包名openclawSkill 文件夹名正是本文主题所在的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 60010 分钟再加上进程启动、JSON 解析等固定开销余量确保外层超时始终大于内层超时避免外层的“假超时”杀死一个仍在正常工作的内部任务。从 Cherry Studio 源码可见类似的超时策略——OpenClawService 中定义OPENCLAW_COMMAND_TIMEOUT_MS 10000作为预检命令超时并通过setTimeoutproc.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 步单次运行本地主 AgentSkill 文档给出的核心命令为openclaw agent --local --agent main --message prompt --json --timeout 600参数逐一说明参数作用说明agent子命令进入 agent 模式而非交互式 TUI--local本地模式仅调用本地配置好的模型与工具不启动远程/云服务--agent main指定 Agent使用 OpenClaw 的主 Agentmain而非自定义子 Agent--message prompt传入提示词prompt 必须作为一个整体带引号参数传递禁止拼接到其他位置--json结构化输出要求以 JSON 载荷返回结果供调用方程序化解析--timeout 600内部超时单次 Agent 运行的内部超时为 600 秒10 分钟小于外层 11 分钟兜底这与 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 的配置同步syncProviderConfigOpenClawService.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 全文失败处理遵循一套明确的判定与上报路径二进制缺失command -v openclaw失败→ 停下请用户在 Code Mate 安装配置缺失onboarding/provider/model/凭据缺失→ 停下请用户在 Code Mate 配置不读取凭据执行失败进程异常、内部超时、JSON 载荷报错→ 按失败上报不将退出码 0 视为成功流程越界TUI、onboarding、登录、写操作→ 一律禁止防止把有界任务变成不受控的交互式会话。仓库侧为这类错误提供了分层兜底OpenClawService通过GatewayStatusstopped | 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-skillsCodeCliService.installCli 在安装 CLI 后调用installCliSkill(preset)将code-mate-openclaw目录通过skillService.syncBuiltinSkill(...)同步为已安装技能removeCli与reconcileCliSkillCodeCliService.ts在工具被卸载或发现缺失时调用skillService.uninstallBuiltinSkill反向清理应用启动进入onAllReady阶段时执行reconcileCliSkills()CodeCliService.ts保证 Skill 与底层二进制状态始终一致。也就是说用户一旦在 Code Mate 中安装了 OpenClawcode-mate-openclaw/SKILL.md就会自动成为可用技能卸载 OpenClaw 后该技能随之移除。Skill 文档中“请用户在 Code Mate 中安装/配置 OpenClaw”的措辞正对应这条自动化链路。与之配套的是模型与网关配置的打通OpenClawService.syncConfigOpenClawService.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 之间的一份“最小调用契约”其精髓可浓缩为四点非交互--local --agent main --message prompt --json --timeout 600单次运行禁止 TUI/onboarding/登录双通道判定进程退出码与 JSON 载荷必须同时为成功才可采信结果安全边界授权目录内默认只读凭据零接触配置缺失即停止并引导用户在 Code Mate 中配置自动化装配Skill 由 CodeCliService 随 OpenClaw 二进制的安装/卸载自动同步配置由 OpenClawService 自动写入并校验。对希望在 Cherry Studio 中通过 Code Mate 使用 OpenClaw 的开发者本文配套源码入口包括Skill 模板、CLI 工具预设、Skill 安装与回收、OpenClaw 网关与配置服务以及预设测试中固化的调用模板。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考