openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-10 12:48:19 +00:00
parent fd06e1e407
commit a6ef99f019
2 changed files with 186 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
docs/zh-CN/gateway/cli-backends.md
View File

@ -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 会话。
<Note>
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将此集成中的 `claude -p` 用法视为已获认可。
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 工作人员告诉我们，允许以 OpenClaw 风格使用 Claude CLI，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 `claude -p` 用法视为此集成场景下被认可的方式。
</Note>
内置的 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.<id>` 中的用户配置仍会覆盖插件默认值。
- 特定后端的配置清理仍通过可选的 `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 支持文件路径）。

280
docs/zh-CN/tools/skills.md
View File

@ -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. **项目智能体技能**：`<workspace>/.agents/skills`
6. **工作区技能**：`<workspace>/skills`
1. **额外 Skills 文件夹**：通过 `skills.load.extraDirs` 配置
2. **内置 Skills**：随安装包一起提供（npm 包或 OpenClaw.app）
3. **托管式/本地 Skills**：`~/.openclaw/skills`
4. **个人 agent Skills**：`~/.agents/skills`
5. **项目 agent Skills**：`<workspace>/.agents/skills`
6. **工作区 Skills**：`<workspace>/skills`
如果技能名称冲突，优先级为：
如果 skill 名称冲突，优先级如下：
`<workspace>/skills`（最高）→ `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置技能 → `skills.load.extraDirs`（最低）
`<workspace>/skills`（最高）→ `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 Skills → `skills.load.extraDirs`（最低）
## 每智能体与共享 Skills
## 每个 agent 的 Skills 与共享 Skills
在**多智能体**设置中，每个智能体都有自己的工作区。这意味着：
- **每智能体技能**位于该智能体专属的 `<workspace>/skills` 中。
- **项目智能体技能**位于 `<workspace>/.agents/skills` 中，并会在常规工作区 `skills/` 文件夹之前应用到
该工作区。
- **个人智能体技能**位于 `~/.agents/skills` 中，并会在该机器上的
各个工作区之间生效。
- **共享技能**位于 `~/.openclaw/skills`（托管/本地）中，并且对同一台机器上的
**所有智能体**可见。
- 如果你希望多个智能体使用一套通用技能包，也可以通过 `skills.load.extraDirs` 添加**共享文件夹**（最低
优先级）。
- **每个 agent 独有的 Skills** 仅存在于该 agent 的 `<workspace>/skills` 中。
- **项目 agent Skills** 位于 `<workspace>/.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 <skill-slug>`
- 更新所有已安装技能：
- 更新所有已安装的 skills：
- `openclaw skills update --all`
- 同步（扫描 + 发布更新）：
- `clawhub sync --all`
原生 `openclaw skills install` 会将技能安装到当前工作区的 `skills/`
目录中。单独的 `clawhub` CLI 也会安装到当前工作目录下的 `./skills`
中（或者回退到已配置的 OpenClaw 工作区）。
OpenClaw 会在下一个会话中将其视为 `<workspace>/skills`。
原生 `openclaw skills install` 会安装到当前活动工作区的 `skills/` 目录中。独立的 `clawhub` CLI 也会安装到当前工作目录下的 `./skills` 中（或者回退到已配置的 OpenClaw 工作区）。
OpenClaw 会在下一个会话中将其识别为 `<workspace>/skills`。
## 安全说明
- 将第三方技能视为**不受信任代码**。启用前请先阅读。
- 对不受信任输入和高风险工具，优先使用沙箱隔离运行。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。
- 工作区和 extra-dir 技能发现只接受技能根目录以及其解析后的 realpath 保持在已配置根目录内的 `SKILL.md` 文件。
- 由 Gateway 网关支持的技能依赖安装（`skills.install`、新手引导和 Skills 设置 UI）会在执行安装器元数据前先运行内置危险代码扫描器。除非调用者显式设置危险覆盖，否则默认会阻止 `critical` 发现；可疑发现仍然只会发出警告。
- `openclaw skills install <slug>` 不同：它会把 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 <slug>` 则不同：它会将一个 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: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`。
## 门控（加载时过滤）
## 门控规则（加载时过滤）
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.<name>.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.<name>.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/<skillKey>`）。
这只影响 **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/<skillKey>`）。
如果不存在 `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.<key>.env` 或 `skills.entries.<key>.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 转义后的 `<name>`、`<description>` 和 `<location>` 值长度。
- **基础开销（仅在 ≥1 个 skill 时）：** 195 个字符。
- **每个 skill：** 97 个字符 + XML 转义后的 `<name>`、`<description>` 和 `<location>` 值的长度。
公式（字符数）：
@ -355,20 +330,17 @@ total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(locati
说明：
- XML 转义会将 `& < > " '` 扩展为实体（`&amp;`、`&lt;` 等），从而增加长度。
- 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) — 插件系统概览