diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index 1c7cad4c0..87667f7c4 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -6,36 +6,36 @@ read_when: summary: CLI 后端：本地 AI CLI 回退，支持可选的 MCP 工具桥接 title: CLI 后端 x-i18n: - generated_at: "2026-04-07T09:37:47Z" + generated_at: "2026-04-08T17:18:40Z" model: gpt-5.4 provider: openai - source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414 + source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 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 分块流式传输**。 +- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 +- 对支持它的 CLI 提供 **JSONL 分块流式传输**。 - **支持会话**（因此后续轮次能保持连贯）。 -- 如果 CLI 接受图片路径，**图片也可以透传**。 +- 如果 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`（允许列表），你也必须把你的 CLI 后端模型包含在其中。 +- 如果主提供商失败（身份验证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。 ## 配置概览 @@ -89,8 +89,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 agents.defaults.cliBackends ``` -每个条目都以**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。 -该提供商 id 会成为你的模型引用左侧部分： +每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。 +这个提供商 id 会成为你的模型引用左侧部分： ``` / @@ -120,6 +120,9 @@ agents.defaults.cliBackends sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", + // Codex 风格的 CLI 也可以改为指向一个提示文件： + // systemPromptFileConfigArg: "-c", + // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -133,58 +136,65 @@ agents.defaults.cliBackends ## 工作原理 -1. 根据提供商前缀（`codex-cli/...`）**选择后端**。 +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 都会将组装后的提示词写入一个临时文件。 + ## 会话 -- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符为 `{sessionId}`）；当需要把该 ID 插入多个标志时可使用后者。 -- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置 `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`（用于非 JSON 恢复）。 +- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 + `sessionArgs`（占位符 `{sessionId}`），当该 ID 需要插入到多个标志中时使用。 +- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置 + `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput` + （用于非 JSON 恢复）。 - `sessionMode`： - - `always`：始终发送会话 id（如果未存储则生成新的 UUID）。 + - `always`：始终发送一个会话 id（如果没有已存储的，则生成新的 UUID）。 - `existing`：仅当之前已存储会话 id 时才发送。 - - `none`：永不发送会话 id。 + - `none`：从不发送会话 id。 序列化说明： -- `serialize: true` 会保持同一通道运行按顺序执行。 +- `serialize: true` 会保持同一通道中的运行按顺序执行。 - 大多数 CLI 会在一个提供商通道上串行执行。 -- 当后端认证状态发生变化时，包括重新登录、令牌轮换或认证配置文件凭证变化，OpenClaw 会丢弃已存储的 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。 -- 对于 Gemini CLI JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。 -- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。 -- `output: "text"` 会将 stdout 视为最终响应。 +- `output: "json"`（默认）会尝试解析 JSON，并提取文本和会话 id。 +- 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。 +- `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"]` @@ -206,29 +216,32 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件：本地 Gemini CLI 必须已安装，并且可以通过 `PATH` 中的 `gemini` 使用（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）。 +前提条件：本地 Gemini CLI 必须已安装，并且可在 +`PATH` 上通过 `gemini` 使用（`brew install gemini-cli` 或 +`npm install -g @google/gemini-cli`）。 Gemini CLI JSON 说明： -- 回复文本从 JSON 的 `response` 字段中读取。 +- 回复文本从 JSON 的 `response` 字段读取。 - 当 `usage` 不存在或为空时，用量会回退到 `stats`。 -- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 -- 如果 `stats.input` 缺失，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 +- `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。 +- 如果 `stats.input` 缺失，OpenClaw 会根据 + `stats.input_tokens - stats.cached` 推导输入 token 数。 -仅在需要时才覆盖这些默认值（常见情况：使用绝对 `command` 路径）。 +仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。 -## 插件所有的默认值 +## 插件自有默认值 -CLI 后端默认值现在属于插件表面的一部分： +CLI 后端默认值现在是插件接口的一部分： -- 插件使用 `api.registerCliBackend(...)` 注册它们。 +- 插件通过 `api.registerCliBackend(...)` 注册它们。 - 后端 `id` 会成为模型引用中的提供商前缀。 -- `agents.defaults.cliBackends.` 中的用户配置仍然会覆盖插件默认值。 -- 后端特定的配置清理由插件通过可选的 `normalizeConfig` hook 负责。 +- `agents.defaults.cliBackends.` 中的用户配置仍会覆盖插件默认值。 +- 特定后端的配置清理仍通过可选的 `normalizeConfig` hook 由插件自行负责。 ## Bundle MCP 覆盖层 -CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择接收生成的 MCP 配置覆盖层。 +CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择启用自动生成的 MCP 配置覆盖层。 当前内置行为： @@ -238,25 +251,27 @@ CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过 启用 bundle MCP 后，OpenClaw 会： -- 启动一个 loopback HTTP MCP 服务器，向 CLI 进程暴露 Gateway 网关工具 -- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证 -- 将工具访问范围限定在当前会话、账户和渠道上下文内 +- 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程 +- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行身份验证 +- 将工具访问范围限制在当前会话、账户和渠道上下文中 - 为当前工作区加载已启用的 bundle-MCP 服务器 -- 将它们与任何现有后端 MCP 配置/设置结构合并 -- 使用所属扩展中的后端所有集成模式重写启动配置 +- 将它们与任何现有的后端 MCP 配置/设置结构合并 +- 使用所属扩展中的后端自有集成模式重写启动配置 如果没有启用任何 MCP 服务器，当后端选择启用 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 ## 限制 -- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入 CLI 后端协议。只有当后端选择启用 `bundleMcp: true` 时，后端才能看到 Gateway 网关工具。 -- **流式传输因后端而异。** 有些后端会流式输出 JSONL，其他后端则会缓冲直到退出。 +- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 + 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 支持文件路径）。 +- **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是 + `none`（Codex CLI 当前无法使用 JSON 输出进行恢复）。 +- **图像被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。