diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index 87667f7c4..3035d5b0f 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -1,41 +1,41 @@ --- read_when: - - 当 API 提供商失败时,你想要一个可靠的回退方案 - - 你正在运行 Codex CLI 或其他本地 AI CLI,并且想要复用它们 - - 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接 + - 当 API 提供商失败时,你需要一个可靠的回退方案 + - 你正在运行 Codex CLI 或其他本地 AI CLI,并希望复用它们 + - 你想了解用于 CLI 后端工具访问的 MCP loopback bridge summary: CLI 后端:本地 AI CLI 回退,支持可选的 MCP 工具桥接 title: CLI 后端 x-i18n: - generated_at: "2026-04-08T17:18:40Z" + generated_at: "2026-04-10T12:46:45Z" model: gpt-5.4 provider: openai - source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 + source_hash: e122831eec29a5df302a7a72e57882c566398d29d6a79be924f601ce2f7a2291 source_path: gateway/cli-backends.md workflow: 15 --- # CLI 后端(回退运行时) -当 API 提供商不可用、受到速率限制或暂时行为异常时,OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退方案**来运行。这种设计刻意保持保守: +当 API 提供商不可用、触发速率限制或暂时行为异常时,OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退**来运行。这一设计有意保持保守: -- **不会直接注入 OpenClaw 工具**,但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 -- 对支持它的 CLI 提供 **JSONL 分块流式传输**。 -- **支持会话**(因此后续轮次能保持连贯)。 -- 如果 CLI 接受图像路径,**图像可以透传**。 +- **不会直接注入 OpenClaw 工具**,但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP bridge 接收 Gateway 网关工具。 +- 对支持的 CLI 提供 **JSONL 流式传输**。 +- **支持会话**(因此后续轮次能够保持连贯)。 +- 如果 CLI 接受图片路径,**图片可以透传**。 -这被设计为一个**安全网**,而不是主路径。当你想要“始终可用”的文本响应,而不依赖外部 API 时,可以使用它。 +这被设计为一个**安全网**,而不是主要路径。当你希望获得“不管怎样都能工作”的文本响应,而不依赖外部 API 时,可以使用它。 -如果你想要一个具备 ACP 会话控制、后台任务、线程/会话绑定以及持久化外部编码会话的完整 harness 运行时,请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 +如果你需要带有 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时,请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 ## 面向初学者的快速开始 -你可以**无需任何配置**就使用 Codex CLI(内置的 OpenAI 插件会注册一个默认后端): +你可以在**无需任何配置**的情况下使用 Codex CLI(内置 OpenAI 插件会注册一个默认后端): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -如果你的 Gateway 网关运行在 launchd/systemd 下,且 `PATH` 很精简,只需添加命令路径: +如果你的 Gateway 网关运行在 launchd/systemd 下,且 PATH 很精简,只需添加命令路径: ```json5 { @@ -51,13 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 } ``` -就是这样。除了 CLI 自身之外,不需要密钥,也不需要额外的身份验证配置。 +就是这样。除 CLI 本身之外,不需要密钥,也不需要额外的凭证配置。 -如果你在 Gateway 网关主机上将某个内置 CLI 后端作为**主要消息提供商**使用,当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时,OpenClaw 现在会自动加载其所属的内置插件。 +如果你在 Gateway 网关主机上将某个内置 CLI 后端作为**主要消息提供商**使用,那么当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时,OpenClaw 现在会自动加载其所属的内置插件。 -## 将它用作回退方案 +## 将其用作回退 -将某个 CLI 后端添加到你的回退列表中,这样它只会在主模型失败时运行: +将一个 CLI 后端添加到你的回退列表中,这样它只会在主模型失败时运行: ```json5 { @@ -78,8 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 说明: -- 如果你使用 `agents.defaults.models`(允许列表),你也必须把你的 CLI 后端模型包含在其中。 -- 如果主提供商失败(身份验证、速率限制、超时),OpenClaw 会接着尝试 CLI 后端。 +- 如果你使用 `agents.defaults.models`(allowlist),你也必须把 CLI 后端模型包含进去。 +- 如果主提供商失败(凭证、速率限制、超时),OpenClaw 会接着尝试 CLI 后端。 ## 配置概览 @@ -120,7 +120,7 @@ agents.defaults.cliBackends sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // Codex 风格的 CLI 也可以改为指向一个提示文件: + // 对于 Codex 风格的 CLI,也可以改为指向一个提示词文件: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -138,63 +138,64 @@ agents.defaults.cliBackends 1. 根据提供商前缀(`codex-cli/...`)**选择一个后端**。 2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。 -3. 使用会话 id(如果支持)**执行 CLI**,以便历史记录保持一致。 -4. **解析输出**(JSON 或纯文本),并返回最终文本。 -5. 按后端**持久化会话 id**,使后续轮次复用相同的 CLI 会话。 +3. 如果支持,则使用会话 id **执行 CLI**,以便历史保持一致。 +4. **解析输出**(JSON 或纯文本)并返回最终文本。 +5. 按后端**持久化会话 id**,以便后续轮次复用相同的 CLI 会话。 -内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们,OpenClaw 风格的 Claude CLI 用法再次被允许,因此除非 Anthropic 发布新的政策,否则 OpenClaw 会将此集成中的 `claude -p` 用法视为已获认可。 +内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 工作人员告诉我们,允许以 OpenClaw 风格使用 Claude CLI,因此除非 Anthropic 发布新的政策,否则 OpenClaw 会将 `claude -p` 用法视为此集成场景下被认可的方式。 内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项(`-c -model_instructions_file="..."`)传递 OpenClaw 的系统提示词。Codex 没有提供类似 Claude 风格的 -`--append-system-prompt` 标志,因此对于每个新的 Codex CLI 会话,OpenClaw 都会将组装后的提示词写入一个临时文件。 +model_instructions_file="..."`)传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的 `--append-system-prompt` 标志,因此对于每个新的 Codex CLI 会话,OpenClaw 都会将组装后的提示词写入一个临时文件。 + +内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw Skills 快照:一种是附加到系统提示词中的精简版 OpenClaw Skills 目录,另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体/会话符合条件的 Skills,因此 Claude Code 原生的技能解析器看到的过滤集合,与 OpenClaw 否则会在提示词中公布的集合相同。对于本次运行,Skill 环境/API 密钥覆盖仍会由 OpenClaw 应用到子进程环境中。 ## 会话 - 如果 CLI 支持会话,请设置 `sessionArg`(例如 `--session-id`)或 - `sessionArgs`(占位符 `{sessionId}`),当该 ID 需要插入到多个标志中时使用。 + `sessionArgs`(占位符 `{sessionId}`),用于在需要将该 ID 插入多个标志时使用。 - 如果 CLI 使用带有不同标志的**恢复子命令**,请设置 `resumeArgs`(恢复时替换 `args`),并可选设置 `resumeOutput` (用于非 JSON 恢复)。 - `sessionMode`: - - `always`:始终发送一个会话 id(如果没有已存储的,则生成新的 UUID)。 + - `always`:始终发送会话 id(如果没有已存储的就生成一个新的 UUID)。 - `existing`:仅当之前已存储会话 id 时才发送。 - `none`:从不发送会话 id。 -序列化说明: +串行化说明: -- `serialize: true` 会保持同一通道中的运行按顺序执行。 -- 大多数 CLI 会在一个提供商通道上串行执行。 -- 当后端身份验证状态发生变化时,包括重新登录、令牌轮换或身份验证配置文件凭证变化,OpenClaw 会丢弃已存储的 CLI 会话复用状态。 +- `serialize: true` 会让同一通道上的运行保持顺序。 +- 大多数 CLI 会在同一提供商通道上串行执行。 +- 当后端凭证状态发生变化时,包括重新登录、令牌轮换或凭证配置文件发生变化,OpenClaw 会丢弃已存储的 CLI 会话复用状态。 -## 图像(透传) +## 图片(透传) -如果你的 CLI 接受图像路径,请设置 `imageArg`: +如果你的 CLI 接受图片路径,请设置 `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`,这些路径会作为 CLI 参数传入。如果没有设置 `imageArg`,OpenClaw 会将文件路径附加到提示词中(路径注入),这对于那些能够从普通路径自动加载本地文件的 CLI 已经足够。 +OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`,这些路径会作为 CLI 参数传递。如果缺少 `imageArg`,OpenClaw 会将文件路径附加到提示词中(路径注入);这对于那些可以从普通路径自动加载本地文件的 CLI 来说已经足够。 ## 输入 / 输出 -- `output: "json"`(默认)会尝试解析 JSON,并提取文本和会话 id。 +- `output: "json"`(默认)会尝试解析 JSON,并提取文本与会话 id。 - 对于 Gemini CLI 的 JSON 输出,当 `usage` 缺失或为空时,OpenClaw 会从 `response` 读取回复文本,并从 `stats` 读取用量。 -- `output: "jsonl"` 会解析 JSONL 流(例如 Codex CLI 的 `--json`),并提取最终的智能体消息以及会话标识符(如果存在)。 -- `output: "text"` 将 stdout 视为最终响应。 +- `output: "jsonl"` 会解析 JSONL 流(例如 Codex CLI `--json`),并提取最终智能体消息以及存在时的会话标识符。 +- `output: "text"` 会将 stdout 视为最终响应。 输入模式: - `input: "arg"`(默认)将提示词作为最后一个 CLI 参数传递。 - `input: "stdin"` 通过 stdin 发送提示词。 -- 如果提示词很长,并且设置了 `maxPromptArgChars`,则会改用 stdin。 +- 如果提示词很长且设置了 `maxPromptArgChars`,则会改用 stdin。 ## 默认值(插件自有) -内置的 OpenAI 插件也为 `codex-cli` 注册了一个默认值: +内置 OpenAI 插件也会为 `codex-cli` 注册一个默认值: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -205,7 +206,7 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`, - `imageArg: "--image"` - `sessionMode: "existing"` -内置的 Google 插件也为 `google-gemini-cli` 注册了一个默认值: +内置 Google 插件也会为 `google-gemini-cli` 注册一个默认值: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -216,15 +217,15 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`, - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件:本地 Gemini CLI 必须已安装,并且可在 -`PATH` 上通过 `gemini` 使用(`brew install gemini-cli` 或 +前提条件:本地 Gemini CLI 必须已安装,并且可以通过 `PATH` 中的 +`gemini` 使用(`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`)。 Gemini CLI JSON 说明: - 回复文本从 JSON 的 `response` 字段读取。 - 当 `usage` 不存在或为空时,用量会回退到 `stats`。 -- `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。 +- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 - 如果 `stats.input` 缺失,OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 @@ -235,43 +236,43 @@ Gemini CLI JSON 说明: CLI 后端默认值现在是插件接口的一部分: - 插件通过 `api.registerCliBackend(...)` 注册它们。 -- 后端 `id` 会成为模型引用中的提供商前缀。 +- 后端的 `id` 会成为模型引用中的提供商前缀。 - `agents.defaults.cliBackends.` 中的用户配置仍会覆盖插件默认值。 -- 特定后端的配置清理仍通过可选的 `normalizeConfig` hook 由插件自行负责。 +- 后端特定的配置清理由可选的 `normalizeConfig` hook 继续保持为插件自有。 ## Bundle MCP 覆盖层 -CLI 后端**不会**直接接收 OpenClaw 工具调用,但后端可以通过设置 `bundleMcp: true` 选择启用自动生成的 MCP 配置覆盖层。 +CLI 后端**不会**直接接收 OpenClaw 工具调用,但后端可以通过设置 `bundleMcp: true` 选择接收一个生成的 MCP 配置覆盖层。 当前内置行为: - `claude-cli`:生成严格的 MCP 配置文件 -- `codex-cli`:为 `mcp_servers` 提供内联配置覆盖 -- `google-gemini-cli`:生成 Gemini 系统设置文件 +- `codex-cli`:对 `mcp_servers` 的内联配置覆盖 +- `google-gemini-cli`:生成 Gemini system settings 文件 -启用 bundle MCP 后,OpenClaw 会: +启用 bundle MCP 时,OpenClaw 会: - 启动一个 loopback HTTP MCP 服务器,将 Gateway 网关工具暴露给 CLI 进程 -- 使用每会话令牌(`OPENCLAW_MCP_TOKEN`)对桥接进行身份验证 +- 使用每会话令牌(`OPENCLAW_MCP_TOKEN`)对 bridge 进行认证 - 将工具访问范围限制在当前会话、账户和渠道上下文中 - 为当前工作区加载已启用的 bundle-MCP 服务器 - 将它们与任何现有的后端 MCP 配置/设置结构合并 -- 使用所属扩展中的后端自有集成模式重写启动配置 +- 使用所属扩展中由后端自有的集成模式重写启动配置 -如果没有启用任何 MCP 服务器,当后端选择启用 bundle MCP 时,OpenClaw 仍会注入严格配置,以便后台运行保持隔离。 +如果没有启用任何 MCP 服务器,只要某个后端选择启用 bundle MCP,OpenClaw 仍会注入严格配置,以便后台运行保持隔离。 ## 限制 - **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 - CLI 后端协议中。只有在后端选择启用 `bundleMcp: true` 时,后端才能看到 Gateway 网关工具。 -- **流式传输是后端特定的。** 某些后端会流式输出 JSONL;其他后端会缓冲直到退出。 + CLI 后端协议中。后端只有在选择启用 `bundleMcp: true` 时才会看到 Gateway 网关工具。 +- **流式传输取决于后端。** 某些后端会流式输出 JSONL;其他后端则会缓冲直到退出。 - **结构化输出** 取决于 CLI 的 JSON 格式。 -- **Codex CLI 会话** 通过文本输出恢复(没有 JSONL),其结构化程度低于初始的 `--json` 运行。但 OpenClaw 会话仍可正常工作。 +- **Codex CLI 会话** 通过文本输出恢复(没有 JSONL),其结构性不如初始的 `--json` 运行。OpenClaw 会话本身仍可正常工作。 ## 故障排除 - **找不到 CLI**:将 `command` 设置为完整路径。 - **模型名称错误**:使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。 - **没有会话连续性**:确保已设置 `sessionArg`,并且 `sessionMode` 不是 - `none`(Codex CLI 当前无法使用 JSON 输出进行恢复)。 -- **图像被忽略**:设置 `imageArg`(并确认 CLI 支持文件路径)。 + `none`(Codex CLI 当前无法通过 JSON 输出恢复)。 +- **图片被忽略**:设置 `imageArg`(并确认 CLI 支持文件路径)。 diff --git a/docs/zh-CN/tools/skills.md b/docs/zh-CN/tools/skills.md index fc9c1053d..9e7bdaf59 100644 --- a/docs/zh-CN/tools/skills.md +++ b/docs/zh-CN/tools/skills.md @@ -1,64 +1,57 @@ --- read_when: - 添加或修改 Skills - - 更改技能门控或加载规则 -summary: Skills:托管与工作区、门控规则,以及 config/env 连接方式 + - 更改 Skills 的门控或加载规则 +summary: Skills:托管式与工作区、门控规则,以及配置/环境变量连接方式 title: Skills x-i18n: - generated_at: "2026-04-05T10:12:58Z" + generated_at: "2026-04-10T12:46:44Z" model: gpt-5.4 provider: openai - source_hash: 6bb0e2e7c2ff50cf19c759ea1da1fd1886dc11f94adc77cbfd816009f75d93ee + source_hash: b1eaf130966950b6eb24f859d9a77ecbf81c6cb80deaaa6a3a79d2c16d83115d source_path: tools/skills.md workflow: 15 --- # Skills(OpenClaw) -OpenClaw 使用与 **[AgentSkills](https://agentskills.io)** 兼容的技能文件夹来教会智能体如何使用工具。每个技能都是一个目录,包含一个带有 YAML frontmatter 和说明的 `SKILL.md`。OpenClaw 会加载**内置技能**以及可选的本地覆盖,并根据环境、配置和二进制文件是否存在,在加载时对它们进行过滤。 +OpenClaw 使用与 **[AgentSkills](https://agentskills.io)** 兼容的技能文件夹来教会智能体如何使用工具。每个 skill 都是一个目录,其中包含带有 YAML frontmatter 和说明的 `SKILL.md`。OpenClaw 会加载**内置 Skills**以及可选的本地覆盖,并在加载时根据环境、配置和二进制文件是否存在进行筛选。 ## 位置和优先级 OpenClaw 会从以下来源加载 Skills: -1. **额外技能文件夹**:通过 `skills.load.extraDirs` 配置 -2. **内置技能**:随安装一起提供(npm 包或 OpenClaw.app) -3. **托管/本地技能**:`~/.openclaw/skills` -4. **个人智能体技能**:`~/.agents/skills` -5. **项目智能体技能**:`/.agents/skills` -6. **工作区技能**:`/skills` +1. **额外 Skills 文件夹**:通过 `skills.load.extraDirs` 配置 +2. **内置 Skills**:随安装包一起提供(npm 包或 OpenClaw.app) +3. **托管式/本地 Skills**:`~/.openclaw/skills` +4. **个人 agent Skills**:`~/.agents/skills` +5. **项目 agent Skills**:`/.agents/skills` +6. **工作区 Skills**:`/skills` -如果技能名称冲突,优先级为: +如果 skill 名称冲突,优先级如下: -`/skills`(最高)→ `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置技能 → `skills.load.extraDirs`(最低) +`/skills`(最高)→ `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 Skills → `skills.load.extraDirs`(最低) -## 每智能体与共享 Skills +## 每个 agent 的 Skills 与共享 Skills 在**多智能体**设置中,每个智能体都有自己的工作区。这意味着: -- **每智能体技能**位于该智能体专属的 `/skills` 中。 -- **项目智能体技能**位于 `/.agents/skills` 中,并会在常规工作区 `skills/` 文件夹之前应用到 - 该工作区。 -- **个人智能体技能**位于 `~/.agents/skills` 中,并会在该机器上的 - 各个工作区之间生效。 -- **共享技能**位于 `~/.openclaw/skills`(托管/本地)中,并且对同一台机器上的 - **所有智能体**可见。 -- 如果你希望多个智能体使用一套通用技能包,也可以通过 `skills.load.extraDirs` 添加**共享文件夹**(最低 - 优先级)。 +- **每个 agent 独有的 Skills** 仅存在于该 agent 的 `/skills` 中。 +- **项目 agent Skills** 位于 `/.agents/skills`,会先于普通工作区 `skills/` 文件夹应用到该工作区。 +- **个人 agent Skills** 位于 `~/.agents/skills`,会应用到该机器上的所有工作区。 +- **共享 Skills** 位于 `~/.openclaw/skills`(托管式/本地),同一台机器上的**所有智能体**都可见。 +- 如果你希望多个智能体共用同一套 Skills,也可以通过 `skills.load.extraDirs` 添加**共享文件夹**(最低优先级)。 -如果同一个技能名称在多个位置都存在,则按常规优先级 -生效:工作区最高,然后是项目智能体技能,再然后是个人智能体技能, -然后是托管/本地,之后是内置,最后是额外目录。 +如果同一个 skill 名称在多个位置都存在,则仍然适用常规优先级:工作区优先,然后是项目 agent Skills,再然后是个人 agent Skills,然后是托管式/本地,再然后是内置,最后是额外目录。 -## 智能体技能允许列表 +## 智能体 Skill 允许列表 -技能**位置**和技能**可见性**是两个独立的控制项。 +Skill 的**位置**和 skill 的**可见性**是两套独立控制。 -- 位置/优先级决定同名技能中哪一个副本胜出。 -- 智能体允许列表决定某个智能体实际上可以使用哪些可见技能。 +- 位置/优先级决定同名 skill 最终使用哪一份副本。 +- 智能体允许列表决定 agent 实际可以使用哪些可见 skills。 -使用 `agents.defaults.skills` 作为共享基线,然后通过 -`agents.list[].skills` 按智能体覆盖: +使用 `agents.defaults.skills` 作为共享基线,然后通过 `agents.list[].skills` 为每个 agent 覆盖: ```json5 { @@ -67,9 +60,9 @@ OpenClaw 会从以下来源加载 Skills: skills: ["github", "weather"], }, list: [ - { id: "writer" }, // 继承 github, weather + { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换 defaults - { id: "locked-down", skills: [] }, // 无技能 + { id: "locked-down", skills: [] }, // 无 skills ], }, } @@ -77,56 +70,44 @@ OpenClaw 会从以下来源加载 Skills: 规则: -- 如果默认希望 Skills 不受限制,请省略 `agents.defaults.skills`。 +- 如果默认不限制 skills,则省略 `agents.defaults.skills`。 - 省略 `agents.list[].skills` 表示继承 `agents.defaults.skills`。 -- 设置 `agents.list[].skills: []` 表示不使用任何技能。 -- 非空的 `agents.list[].skills` 列表就是该智能体的最终技能集合;它 - 不会与默认值合并。 +- 设置 `agents.list[].skills: []` 表示没有 skills。 +- 非空的 `agents.list[].skills` 列表就是该 agent 的最终集合;它不会与 defaults 合并。 -OpenClaw 会在提示词构建、技能 slash-command 发现、沙箱同步以及技能快照中应用该智能体的有效技能集。 +OpenClaw 会在构建提示词、skill 斜杠命令发现、沙箱同步以及 skill 快照时应用 agent 的最终有效 skill 集合。 ## 插件 + Skills -插件可以通过在 -`openclaw.plugin.json` 中列出 `skills` 目录(相对于插件根目录的路径)来提供自己的技能。插件技能会在插件启用时加载。当前这些目录会被合并到与 `skills.load.extraDirs` 相同的 -低优先级路径中,因此同名的内置、 -托管、智能体或工作区技能都会覆盖它们。 -你可以通过插件配置项上的 `metadata.openclaw.requires.config` 对它们进行门控。 -关于发现/配置请参阅 [插件](/zh-CN/tools/plugin),关于这些技能所教授的 -工具表面请参阅 [工具](/zh-CN/tools)。 +插件可以通过在 `openclaw.plugin.json` 中列出 `skills` 目录来附带自己的 Skills(路径相对于插件根目录)。插件启用后,这些插件 Skills 就会加载。当前这些目录会被合并到与 `skills.load.extraDirs` 相同的低优先级路径中,因此同名的内置、托管式、agent 或工作区 skill 都会覆盖它们。 +你可以通过插件配置项上的 `metadata.openclaw.requires.config` 对它们进行门控。有关发现/配置,请参阅 [Plugins](/zh-CN/tools/plugin);有关这些 skills 所教授的工具界面,请参阅 [Tools](/zh-CN/tools)。 ## ClawHub(安装 + 同步) -ClawHub 是 OpenClaw 的公开技能注册表。浏览地址: -[https://clawhub.ai](https://clawhub.ai)。使用原生 `openclaw skills` -命令来发现/安装/更新技能;如果 -你需要发布/同步工作流,则使用单独的 `clawhub` CLI。 +ClawHub 是 OpenClaw 的公共 Skills 注册表。可在 [https://clawhub.ai](https://clawhub.ai) 浏览。使用原生 `openclaw skills` 命令来发现/安装/更新 skills;如果你需要发布/同步工作流,也可以使用独立的 `clawhub` CLI。 完整指南:[ClawHub](/zh-CN/tools/clawhub)。 常见流程: -- 将某个技能安装到你的工作区: +- 将 skill 安装到你的工作区: - `openclaw skills install ` -- 更新所有已安装技能: +- 更新所有已安装的 skills: - `openclaw skills update --all` - 同步(扫描 + 发布更新): - `clawhub sync --all` -原生 `openclaw skills install` 会将技能安装到当前工作区的 `skills/` -目录中。单独的 `clawhub` CLI 也会安装到当前工作目录下的 `./skills` -中(或者回退到已配置的 OpenClaw 工作区)。 -OpenClaw 会在下一个会话中将其视为 `/skills`。 +原生 `openclaw skills install` 会安装到当前活动工作区的 `skills/` 目录中。独立的 `clawhub` CLI 也会安装到当前工作目录下的 `./skills` 中(或者回退到已配置的 OpenClaw 工作区)。 +OpenClaw 会在下一个会话中将其识别为 `/skills`。 ## 安全说明 -- 将第三方技能视为**不受信任代码**。启用前请先阅读。 -- 对不受信任输入和高风险工具,优先使用沙箱隔离运行。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。 -- 工作区和 extra-dir 技能发现只接受技能根目录以及其解析后的 realpath 保持在已配置根目录内的 `SKILL.md` 文件。 -- 由 Gateway 网关支持的技能依赖安装(`skills.install`、新手引导和 Skills 设置 UI)会在执行安装器元数据前先运行内置危险代码扫描器。除非调用者显式设置危险覆盖,否则默认会阻止 `critical` 发现;可疑发现仍然只会发出警告。 -- `openclaw skills install ` 不同:它会把 ClawHub 技能文件夹下载到工作区中,而不会使用上面的安装器元数据路径。 -- `skills.entries.*.env` 和 `skills.entries.*.apiKey` 会将密钥注入该智能体轮次的**主机**进程 - 中(不是沙箱)。请将密钥保留在提示词和日志之外。 -- 更广泛的威胁模型与检查清单,请参阅 [Security](/zh-CN/gateway/security)。 +- 将第三方 skills 视为**不受信任的代码**。启用前请先阅读。 +- 对不受信任的输入和高风险工具,优先使用沙箱隔离运行。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +- 工作区和额外目录的 skill 发现只接受那些其解析后的真实路径仍位于已配置根目录内的 skill 根目录和 `SKILL.md` 文件。 +- 由 Gateway 网关支持的 skill 依赖安装(`skills.install`、新手引导以及 Skills 设置 UI)会在执行安装器元数据之前运行内置危险代码扫描器。默认情况下,`critical` 级别发现会阻止继续,除非调用方显式设置危险覆盖;可疑发现仍然只会发出警告。 +- `openclaw skills install ` 则不同:它会将一个 ClawHub skill 文件夹下载到工作区中,不会使用上述安装器元数据路径。 +- `skills.entries.*.env` 和 `skills.entries.*.apiKey` 会将密钥注入该 agent 当前轮次的**宿主机**进程(而不是沙箱)。不要将密钥放进提示词和日志。 +- 更完整的威胁模型和检查清单,参见 [Security](/zh-CN/gateway/security)。 ## 格式(AgentSkills + Pi 兼容) @@ -141,24 +122,24 @@ description: Generate or edit images via a provider-backed image workflow 说明: -- 我们遵循 AgentSkills 规范的布局/意图。 -- 嵌入式智能体使用的解析器仅支持**单行** frontmatter 键。 +- 我们遵循 AgentSkills 规范中的布局和意图。 +- 嵌入式 agent 使用的解析器仅支持**单行** frontmatter 键。 - `metadata` 应为**单行 JSON 对象**。 -- 在说明中使用 `{baseDir}` 来引用技能文件夹路径。 -- 可选 frontmatter 键: - - `homepage` — 在 macOS Skills UI 中显示为 “Website” 的 URL(也支持通过 `metadata.openclaw.homepage` 设置)。 - - `user-invocable` — `true|false`(默认:`true`)。为 `true` 时,该技能会作为用户 slash 命令公开。 - - `disable-model-invocation` — `true|false`(默认:`false`)。为 `true` 时,该技能会从模型提示词中排除(但仍可通过用户调用使用)。 - - `command-dispatch` — `tool`(可选)。设为 `tool` 时,slash 命令会绕过模型,直接分发到工具。 - - `command-tool` — 当设置 `command-dispatch: tool` 时要调用的工具名称。 - - `command-arg-mode` — `raw`(默认)。对于工具分发,会将原始参数字符串转发给工具(不做核心解析)。 +- 在说明中使用 `{baseDir}` 来引用 skill 文件夹路径。 +- 可选的 frontmatter 键: + - `homepage` — 作为“Website”显示在 macOS Skills UI 中的 URL(也可通过 `metadata.openclaw.homepage` 提供)。 + - `user-invocable` — `true|false`(默认:`true`)。当为 `true` 时,该 skill 会作为用户斜杠命令公开。 + - `disable-model-invocation` — `true|false`(默认:`false`)。当为 `true` 时,该 skill 会从模型提示词中排除(但仍可通过用户调用使用)。 + - `command-dispatch` — `tool`(可选)。设置为 `tool` 时,斜杠命令会绕过模型并直接分发到工具。 + - `command-tool` — 当设置了 `command-dispatch: tool` 时要调用的工具名称。 + - `command-arg-mode` — `raw`(默认)。对于工具分发,会转发原始参数字符串给工具(核心不解析)。 工具会使用以下参数调用: `{ command: "", commandName: "", skillName: "" }`。 -## 门控(加载时过滤) +## 门控规则(加载时过滤) -OpenClaw 会在**加载时**使用 `metadata`(单行 JSON)过滤 Skills: +OpenClaw 会使用 `metadata`(单行 JSON)在**加载时过滤 skills**: ```markdown --- @@ -177,26 +158,25 @@ metadata: `metadata.openclaw` 下的字段: -- `always: true` — 始终包含该技能(跳过其他门控)。 -- `emoji` — macOS Skills UI 使用的可选表情符号。 -- `homepage` — 在 macOS Skills UI 中显示为 “Website” 的可选 URL。 -- `os` — 可选平台列表(`darwin`、`linux`、`win32`)。设置后,技能仅在这些操作系统上符合条件。 -- `requires.bins` — 列表;每个都必须存在于 `PATH` 中。 -- `requires.anyBins` — 列表;其中至少一个必须存在于 `PATH` 中。 -- `requires.env` — 列表;环境变量必须存在,**或者**在配置中提供。 -- `requires.config` — 必须为真值的 `openclaw.json` 路径列表。 -- `primaryEnv` — 与 `skills.entries..apiKey` 关联的环境变量名。 -- `install` — macOS Skills UI 使用的可选安装器规范数组(brew/node/go/uv/download)。 +- `always: true` — 始终包含该 skill(跳过其他门控)。 +- `emoji` — 可选 emoji,供 macOS Skills UI 使用。 +- `homepage` — 可选 URL,作为“Website”显示在 macOS Skills UI 中。 +- `os` — 可选平台列表(`darwin`、`linux`、`win32`)。如已设置,则该 skill 仅在这些操作系统上可用。 +- `requires.bins` — 列表;每一项都必须存在于 `PATH` 中。 +- `requires.anyBins` — 列表;至少有一项必须存在于 `PATH` 中。 +- `requires.env` — 列表;环境变量必须存在,**或**在配置中提供。 +- `requires.config` — `openclaw.json` 路径列表;这些路径必须为真值。 +- `primaryEnv` — 与 `skills.entries..apiKey` 关联的环境变量名称。 +- `install` — 可选的安装器规范数组,供 macOS Skills UI 使用(brew/node/go/uv/download)。 关于沙箱隔离的说明: -- `requires.bins` 会在技能加载时于**主机**上检查。 -- 如果某个智能体处于沙箱中,则该二进制文件也必须**在容器内**存在。 - 请通过 `agents.defaults.sandbox.docker.setupCommand`(或自定义镜像)安装它。 +- `requires.bins` 会在 skill 加载时于**宿主机**上检查。 +- 如果某个 agent 运行在沙箱中,该二进制文件也必须存在于**容器内部**。 + 请通过 `agents.defaults.sandbox.docker.setupCommand`(或自定义镜像)进行安装。 `setupCommand` 会在容器创建后运行一次。 - 软件包安装还需要网络出站、可写根文件系统以及沙箱中的 root 用户。 - 示例:`summarize` 技能(`skills/summarize/SKILL.md`)需要在沙箱容器中存在 `summarize` CLI - 才能在其中运行。 + 安装软件包还需要网络出口、可写的根文件系统以及沙箱中的 root 用户。 + 示例:`summarize` skill(`skills/summarize/SKILL.md`)如果要在沙箱容器中运行,就需要容器内提供 `summarize` CLI。 安装器示例: @@ -227,27 +207,23 @@ metadata: 说明: -- 如果列出了多个安装器,gateway 会选择**单个**首选项(有 brew 时优先 brew,否则使用 node)。 -- 如果所有安装器都是 `download`,OpenClaw 会列出每个条目,以便你查看可用构件。 -- 安装器规范可以包含 `os: ["darwin"|"linux"|"win32"]`,按平台过滤选项。 +- 如果列出了多个安装器,Gateway 网关会选择**一个**首选方案(有 brew 时优先 brew,否则优先 node)。 +- 如果所有安装器都是 `download`,OpenClaw 会列出每个条目,以便你查看所有可用制品。 +- 安装器规范可包含 `os: ["darwin"|"linux"|"win32"]`,用于按平台过滤选项。 - Node 安装会遵循 `openclaw.json` 中的 `skills.install.nodeManager`(默认:npm;可选:npm/pnpm/yarn/bun)。 - 这只影响**技能安装**;Gateway 网关运行时仍应使用 Node - (WhatsApp/Telegram 不推荐使用 Bun)。 -- 由 Gateway 网关支持的安装器选择是基于偏好而不是仅限 node: - 当安装规范混合多种类型时,若启用了 - `skills.install.preferBrew` 且存在 `brew`,OpenClaw 会优先选择 Homebrew,然后是 `uv`,再然后是 - 已配置的 node manager,最后才是 `go` 或 `download` 等其他回退选项。 -- 如果每个安装规范都是 `download`,OpenClaw 会显示所有下载选项, - 而不是折叠成一个首选安装器。 -- Go 安装:如果缺少 `go` 但可用 `brew`,gateway 会先通过 Homebrew 安装 Go,并在可能时将 `GOBIN` 设置为 Homebrew 的 `bin`。 -- Download 安装:`url`(必填)、`archive`(`tar.gz` | `tar.bz2` | `zip`)、`extract`(默认:检测到归档时自动)、`stripComponents`、`targetDir`(默认:`~/.openclaw/tools/`)。 + 这只影响 **skill 安装**;Gateway 网关运行时仍应使用 Node + (不建议在 WhatsApp/Telegram 场景下使用 Bun)。 +- Gateway 网关支持的安装器选择是基于偏好规则的,而不只是 node: + 当安装规范混合多种类型时,OpenClaw 会在启用 `skills.install.preferBrew` 且检测到 `brew` 时优先使用 Homebrew,然后是 `uv`,再然后是已配置的 node 管理器,最后才是 `go` 或 `download` 等其他回退方案。 +- 如果每个安装规范都是 `download`,OpenClaw 会展示所有下载选项,而不是收敛为单一首选安装器。 +- Go 安装:如果缺少 `go` 但存在 `brew`,Gateway 网关会先通过 Homebrew 安装 Go,并尽可能将 `GOBIN` 设为 Homebrew 的 `bin`。 +- 下载安装:`url`(必填)、`archive`(`tar.gz` | `tar.bz2` | `zip`)、`extract`(默认:检测到归档时自动提取)、`stripComponents`、`targetDir`(默认:`~/.openclaw/tools/`)。 -如果不存在 `metadata.openclaw`,则该技能始终符合条件(除非 -在配置中被禁用,或对于内置技能被 `skills.allowBundled` 阻止)。 +如果不存在 `metadata.openclaw`,则该 skill 始终符合加载条件(除非它在配置中被禁用,或作为内置 skill 被 `skills.allowBundled` 阻止)。 ## 配置覆盖(`~/.openclaw/openclaw.json`) -内置/托管技能可以切换开关并提供 env 值: +可以切换内置/托管式 skills,并为它们提供环境变量值: ```json5 { @@ -271,62 +247,61 @@ metadata: } ``` -注意:如果技能名称包含连字符,请给键加引号(JSON5 允许带引号的键)。 +注意:如果 skill 名称包含连字符,请给键名加引号(JSON5 允许带引号的键)。 -如果你想在 OpenClaw 本身中使用标准图像生成/编辑,请使用核心 -`image_generate` 工具并配合 `agents.defaults.imageGenerationModel`,而不是 -内置技能。这里的技能示例适用于自定义或第三方工作流。 +如果你想在 OpenClaw 本身内部使用内置图像生成/编辑,请使用核心 +`image_generate` 工具,并配合 `agents.defaults.imageGenerationModel`,而不是使用某个内置 skill。这里的 skill 示例适用于自定义或第三方工作流。 -对于原生图像分析,请使用带 `agents.defaults.imageModel` 的 `image` 工具。 -对于原生图像生成/编辑,请使用 -带 `agents.defaults.imageGenerationModel` 的 `image_generate`。如果你选择 `openai/*`、`google/*`、 -`fal/*` 或其他提供商特定图像模型,请同时添加该提供商的 auth/API +对于原生图像分析,请使用 `image` 工具并配合 `agents.defaults.imageModel`。 +对于原生图像生成/编辑,请使用 `image_generate` 并配合 +`agents.defaults.imageGenerationModel`。如果你选择 `openai/*`、`google/*`、 +`fal/*` 或其他提供商特定的图像模型,还需要添加该提供商的认证/API 密钥。 -默认情况下,配置键与**技能名称**匹配。如果某个技能定义了 -`metadata.openclaw.skillKey`,则在 `skills.entries` 下请使用该键。 +默认情况下,配置键与**skill 名称**一致。如果某个 skill 定义了 +`metadata.openclaw.skillKey`,则应在 `skills.entries` 下使用该键。 规则: -- `enabled: false` 会禁用该技能,即使它是内置/已安装的。 -- `env`:**仅在**进程中尚未设置该变量时才注入。 -- `apiKey`:为声明了 `metadata.openclaw.primaryEnv` 的技能提供的便利字段。 +- `enabled: false` 即使在该 skill 已内置/已安装的情况下,也会禁用它。 +- `env`:**仅当**该变量尚未在进程中设置时才会注入。 +- `apiKey`:为声明了 `metadata.openclaw.primaryEnv` 的 skills 提供的便捷方式。 支持明文字符串或 SecretRef 对象(`{ source, provider, id }`)。 -- `config`:用于自定义每技能字段的可选容器;自定义键必须放在这里。 -- `allowBundled`:仅适用于**内置**技能的可选允许列表。设置后,只有 - 列表中的内置技能才符合条件(不影响托管/工作区技能)。 +- `config`:用于自定义每个 skill 字段的可选字段包;自定义键必须放在这里。 +- `allowBundled`:仅针对**内置** skills 的可选允许列表。如果设置了它,则只有列表中的内置 skills 符合条件(不影响托管式/工作区 Skills)。 -## 环境注入(每次智能体运行) +## 环境变量注入(每次 agent 运行) -当一次智能体运行开始时,OpenClaw 会: +当一次 agent 运行开始时,OpenClaw 会: -1. 读取技能元数据。 +1. 读取 skill 元数据。 2. 将任意 `skills.entries..env` 或 `skills.entries..apiKey` 应用到 `process.env`。 -3. 用**符合条件的**技能构建系统提示词。 +3. 使用**符合条件的** Skills 构建系统提示词。 4. 在运行结束后恢复原始环境。 -这**只作用于该次智能体运行**,而不是全局 shell 环境。 +这是**限定在 agent 运行范围内**的,不是全局 shell 环境。 + +对于内置的 `claude-cli` 后端,OpenClaw 还会将相同的符合条件快照具体化为一个临时 Claude Code 插件,并通过 `--plugin-dir` 传入。随后 Claude Code 就可以使用其原生 skill 解析器,而 OpenClaw 仍然负责优先级、每个 agent 的允许列表、门控规则,以及 +`skills.entries.*` 环境变量/API 密钥注入。其他 CLI 后端仅使用提示词目录。 ## 会话快照(性能) -OpenClaw 会在会话开始时对符合条件的技能进行快照,并在同一会话的后续轮次中复用该列表。对技能或配置的更改会在下一次新会话中生效。 +OpenClaw 会在会话开始时对符合条件的 Skills 进行快照,并在同一会话的后续轮次中复用该列表。对 skills 或配置的更改会在下一个新会话中生效。 -当启用技能监视器,或出现新的符合条件的远程节点时,技能也可以在会话中途刷新(见下文)。可以把这理解为一种**热重载**:刷新的列表会在下一轮智能体调用时被拾取。 +启用 skills 监视器时,或者当新的符合条件的远程节点出现时,Skills 也可以在会话中途刷新(见下文)。你可以将其理解为一种**热重载**:刷新后的列表会在下一次 agent 轮次中生效。 -如果该会话的有效智能体技能允许列表发生变化,OpenClaw -会刷新快照,以便可见技能与当前 -智能体保持一致。 +如果该会话的有效 agent skill 允许列表发生变化,OpenClaw 会刷新快照,以便可见 Skills 始终与当前 agent 保持一致。 -## 远程 macOS 节点(Linux gateway) +## 远程 macOS 节点(Linux Gateway 网关) -如果 Gateway 网关运行在 Linux 上,但连接了一个**允许 `system.run` 的 macOS 节点**(Exec 审批安全性未设为 `deny`),当该节点上存在所需二进制文件时,OpenClaw 可以将仅限 macOS 的技能视为符合条件。智能体应通过 `exec` 工具并使用 `host=node` 来执行这些技能。 +如果 Gateway 网关运行在 Linux 上,但已连接了一个**允许 `system.run` 的 macOS 节点**(Exec approvals 安全设置不为 `deny`),那么当该节点上存在所需二进制文件时,OpenClaw 可以将仅限 macOS 的 skills 视为符合条件。智能体应通过 `exec` 工具并使用 `host=node` 来执行这些 skills。 -这依赖于节点报告其命令支持情况,并通过 `system.run` 进行 bin 探测。如果该 macOS 节点之后离线,这些技能仍然可见;在节点重新连接之前,调用可能会失败。 +这依赖于节点报告其命令支持情况,并通过 `system.run` 完成二进制探测。如果该 macOS 节点之后离线,这些 skills 仍会保持可见;但在节点重新连接之前,调用可能会失败。 ## Skills 监视器(自动刷新) -默认情况下,OpenClaw 会监视技能文件夹,并在 `SKILL.md` 文件发生变化时更新技能快照。可在 `skills.load` 下进行配置: +默认情况下,OpenClaw 会监视 skill 文件夹,并在 `SKILL.md` 文件发生变化时更新 skills 快照。可在 `skills.load` 下配置: ```json5 { @@ -339,12 +314,12 @@ OpenClaw 会在会话开始时对符合条件的技能进行快照,并在同 } ``` -## Token 影响(技能列表) +## Token 影响(Skills 列表) -当技能符合条件时,OpenClaw 会将一个紧凑的可用技能 XML 列表注入系统提示词(通过 `pi-coding-agent` 中的 `formatSkillsForPrompt`)。成本是确定性的: +当有符合条件的 Skills 时,OpenClaw 会将一份紧凑的可用 Skills XML 列表注入系统提示词中(通过 `pi-coding-agent` 中的 `formatSkillsForPrompt`)。其成本是确定性的: -- **基础开销(仅当 ≥1 个技能时):**195 个字符。 -- **每个技能:**97 个字符 + XML 转义后的 ``、`` 和 `` 值长度。 +- **基础开销(仅在 ≥1 个 skill 时):** 195 个字符。 +- **每个 skill:** 97 个字符 + XML 转义后的 ``、`` 和 `` 值的长度。 公式(字符数): @@ -355,20 +330,17 @@ total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(locati 说明: - XML 转义会将 `& < > " '` 扩展为实体(`&`、`<` 等),从而增加长度。 -- Token 计数会因模型 tokenizer 而异。粗略按 OpenAI 风格估算约为 ~4 字符/token,因此**97 个字符 ≈ 24 个 token**,每个技能还需再加上你的实际字段长度。 +- Token 数量会因模型分词器而异。一个粗略的 OpenAI 风格估算是约 4 个字符/Token,因此**97 个字符 ≈ 24 个 Token**,再加上你实际字段内容的长度。 -## 托管技能生命周期 +## 托管式 Skills 生命周期 -OpenClaw 会随安装提供一组基线技能,作为 -**内置技能**(npm 包或 OpenClaw.app 的一部分)。`~/.openclaw/skills` 用于本地 -覆盖(例如,在不修改内置 -副本的情况下固定/修补某个技能)。工作区技能由用户持有,并会在同名冲突时覆盖前两者。 +OpenClaw 会随安装包(npm 包或 OpenClaw.app)附带一组基础 Skills,作为**内置 Skills**。`~/.openclaw/skills` 用于本地覆盖(例如,在不更改内置副本的情况下固定/修补某个 skill)。工作区 Skills 由用户自行管理,并且在名称冲突时会覆盖两者。 ## 配置参考 -完整配置 schema 请参阅 [Skills 配置](/zh-CN/tools/skills-config)。 +完整配置模式请参阅 [Skills 配置](/zh-CN/tools/skills-config)。 -## 想找更多技能? +## 想找更多 Skills? 浏览 [https://clawhub.ai](https://clawhub.ai)。 @@ -376,7 +348,7 @@ OpenClaw 会随安装提供一组基线技能,作为 ## 相关内容 -- [创建技能](/zh-CN/tools/creating-skills) — 构建自定义技能 -- [Skills 配置](/zh-CN/tools/skills-config) — 技能配置参考 -- [Slash Commands](/zh-CN/tools/slash-commands) — 所有可用的 slash 命令 -- [插件](/zh-CN/tools/plugin) — 插件系统概览 +- [创建 Skills](/zh-CN/tools/creating-skills) — 构建自定义 skills +- [Skills 配置](/zh-CN/tools/skills-config) — skill 配置参考 +- [斜杠命令](/zh-CN/tools/slash-commands) — 所有可用的斜杠命令 +- [Plugins](/zh-CN/tools/plugin) — 插件系统概览