@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/start/wizard-cli-reference.md

@@ -0,0 +1,306 @@
+---
+read_when:
+  - 你需要了解 `quantumclaw onboard` 的详细行为
+  - 你正在调试新手引导结果或集成新手引导客户端
+sidebarTitle: CLI reference
+summary: CLI 设置流程、身份验证/模型设置、输出和内部机制的完整参考
+title: CLI 设置参考
+x-i18n:
+  generated_at: "2026-03-16T06:28:34Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 6b9460013b6a0fbd59f639ade6b255c8d7f7412238495e78b942859ade695e86
+  source_path: start/wizard-cli-reference.md
+  workflow: 15
+---
+
+# CLI 设置参考
+
+本页是 `quantumclaw onboard` 的完整参考。
+简短指南请参见 [设置向导（CLI）](/start/wizard)。
+
+## 向导会执行什么
+
+本地模式（默认）会引导你完成以下内容：
+
+- 模型和身份验证设置（OpenAI Code 订阅 OAuth、Anthropic API 密钥或 setup token，以及 MiniMax、GLM、Ollama、Moonshot 和 AI Gateway 选项）
+- 工作区位置和 bootstrap 文件
+- Gateway 网关设置（端口、绑定、身份验证、tailscale）
+- 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
+- 守护进程安装（LaunchAgent 或 systemd 用户单元）
+- 健康检查
+- Skills 设置
+
+远程模式会将此机器配置为连接到其他位置的网关。
+它不会在远程主机上安装或修改任何内容。
+
+## 本地流程详情
+
+<Steps>
+  <Step title="现有配置检测">
+    - 如果 `~/.quantumclaw/quantumclaw.json` 存在，可选择 Keep、Modify 或 Reset。
+    - 重新运行向导不会清除任何内容，除非你明确选择 Reset（或传递 `--reset`）。
+    - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 还会删除工作区。
+    - 如果配置无效或包含旧版键，向导会停止，并要求你先运行 `quantumclaw doctor` 再继续。
+    - Reset 使用 `trash`，并提供以下范围：
+      - 仅配置
+      - 配置 + 凭证 + 会话
+      - 完全重置（也会删除工作区）
+  </Step>
+  <Step title="模型和身份验证">
+    - 完整选项矩阵见 [身份验证和模型选项](#auth-and-model-options)。
+  </Step>
+  <Step title="工作区">
+    - 默认值为 `~/.quantumclaw/workspace`（可配置）。
+    - 会植入首次运行 bootstrap 仪式所需的工作区文件。
+    - 工作区布局：[智能体工作区](/concepts/agent-workspace)。
+  </Step>
+  <Step title="Gateway 网关">
+    - 会提示你输入端口、绑定、身份验证模式和 tailscale 暴露设置。
+    - 建议：即使仅用于 loopback，也保持启用令牌身份验证，这样本地 WS 客户端也必须进行身份验证。
+    - 在令牌模式下，交互式设置提供：
+      - **生成/存储明文令牌**（默认）
+      - **使用 SecretRef**（可选）
+    - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
+    - 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
+      - 要求在新手引导进程环境中存在一个非空环境变量。
+      - 不能与 `--gateway-token` 组合使用。
+    - 仅当你完全信任每个本地进程时才禁用身份验证。
+    - 非 loopback 绑定仍然需要身份验证。
+  </Step>
+  <Step title="渠道">
+    - [WhatsApp](/channels/whatsapp)：可选 QR 登录
+    - [Telegram](/channels/telegram)：bot 令牌
+    - [Discord](/channels/discord)：bot 令牌
+    - [Google Chat](/channels/googlechat)：服务账号 JSON + webhook audience
+    - [Mattermost](/channels/mattermost) 插件：bot 令牌 + 基础 URL
+    - [Signal](/channels/signal)：可选 `signal-cli` 安装 + 账户配置
+    - [BlueBubbles](/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook
+    - [iMessage](/channels/imessage)：旧版 `imsg` CLI 路径 + 数据库访问
+    - 私信安全：默认是配对。首次私信会发送一个代码；通过
+      `quantumclaw pairing approve <channel> <code>` 批准，或使用 allowlist。
+  </Step>
+  <Step title="守护进程安装">
+    - macOS：LaunchAgent
+      - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
+    - Linux 和通过 WSL2 的 Windows：systemd 用户单元
+      - 向导会尝试执行 `loginctl enable-linger <user>`，使网关在注销后仍保持运行。
+      - 可能会提示输入 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。
+    - 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不建议使用 Bun。
+  </Step>
+  <Step title="健康检查">
+    - 启动 Gateway 网关（如有需要），并运行 `quantumclaw health`。
+    - `quantumclaw status --deep` 会在状态输出中添加 Gateway 网关健康探测。
+  </Step>
+  <Step title="Skills">
+    - 读取可用的 Skills 并检查要求。
+    - 让你选择 node 管理器：npm 或 pnpm（不建议使用 bun）。
+    - 安装可选依赖（部分依赖在 macOS 上使用 Homebrew）。
+  </Step>
+  <Step title="完成">
+    - 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。
+  </Step>
+</Steps>
+
+<Note>
+如果未检测到 GUI，向导会打印用于控制 UI 的 SSH 端口转发说明，而不是打开浏览器。
+如果缺少控制 UI 资源，向导会尝试构建它们；回退命令为 `pnpm ui:build`（首次运行会自动安装 UI 依赖）。
+</Note>
+
+## 远程模式详情
+
+远程模式会将此机器配置为连接到其他位置的网关。
+
+<Info>
+远程模式不会在远程主机上安装或修改任何内容。
+</Info>
+
+你需要设置的内容：
+
+- 远程 Gateway 网关 URL（`ws://...`）
+- 如果远程 Gateway 网关需要身份验证，则设置令牌（推荐）
+
+<Note>
+- 如果网关仅绑定到 loopback，请使用 SSH 隧道或 tailnet。
+- 发现提示：
+  - macOS：Bonjour（`dns-sd`）
+  - Linux：Avahi（`avahi-browse`）
+</Note>
+
+## 身份验证和模型选项
+
+<AccordionGroup>
+  <Accordion title="Anthropic API 密钥">
+    如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后保存以供守护进程使用。
+  </Accordion>
+  <Accordion title="Anthropic OAuth（Claude Code CLI）">
+    - macOS：检查 Keychain 条目 “Claude Code-credentials”
+    - Linux 和 Windows：如果存在，则复用 `~/.claude/.credentials.json`
+
+    在 macOS 上，请选择 “Always Allow”，以免 launchd 启动被阻塞。
+
+  </Accordion>
+  <Accordion title="Anthropic token（粘贴 setup token）">
+    在任意机器上运行 `claude setup-token`，然后粘贴该令牌。
+    你可以为其命名；留空则使用默认值。
+  </Accordion>
+  <Accordion title="OpenAI Code 订阅（复用 Codex CLI）">
+    如果存在 `~/.codex/auth.json`，向导可以复用它。
+  </Accordion>
+  <Accordion title="OpenAI Code 订阅（OAuth）">
+    浏览器流程；粘贴 `code#state`。
+
+    当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
+
+  </Accordion>
+  <Accordion title="OpenAI API 密钥">
+    如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将该凭证存储在 auth profile 中。
+
+    当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.1-codex`。
+
+  </Accordion>
+  <Accordion title="xAI（Grok）API 密钥">
+    提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
+  </Accordion>
+  <Accordion title="OpenCode">
+    提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并让你选择 Zen 或 Go 目录。
+    设置 URL：[opencode.ai/auth](https://opencode.ai/auth)。
+  </Accordion>
+  <Accordion title="API 密钥（通用）">
+    会为你存储该密钥。
+  </Accordion>
+  <Accordion title="Vercel AI Gateway">
+    提示输入 `AI_GATEWAY_API_KEY`。
+    更多详情：[Vercel AI Gateway](/providers/vercel-ai-gateway)。
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway">
+    提示输入账户 ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
+    更多详情：[Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)。
+  </Accordion>
+  <Accordion title="MiniMax M2.5">
+    配置会自动写入。
+    更多详情：[MiniMax](/providers/minimax)。
+  </Accordion>
+  <Accordion title="Synthetic（兼容 Anthropic）">
+    提示输入 `SYNTHETIC_API_KEY`。
+    更多详情：[Synthetic](/providers/synthetic)。
+  </Accordion>
+  <Accordion title="Ollama（Cloud 和本地开放模型）">
+    提示输入基础 URL（默认 `http://127.0.0.1:11434`），然后提供 Cloud + Local 或 Local 模式。
+    会发现可用模型并建议默认值。
+    更多详情：[Ollama](/providers/ollama)。
+  </Accordion>
+  <Accordion title="Moonshot 和 Kimi Coding">
+    Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。
+    更多详情：[Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)。
+  </Accordion>
+  <Accordion title="自定义提供商">
+    适用于兼容 OpenAI 和兼容 Anthropic 的端点。
+
+    交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项：
+    - **现在粘贴 API 密钥**（明文）
+    - **使用密钥引用**（环境变量引用或已配置提供商引用，并带有预检验证）
+
+    非交互式标志：
+    - `--auth-choice custom-api-key`
+    - `--custom-base-url`
+    - `--custom-model-id`
+    - `--custom-api-key`（可选；回退到 `CUSTOM_API_KEY`）
+    - `--custom-provider-id`（可选）
+    - `--custom-compatibility <openai|anthropic>`（可选；默认 `openai`）
+
+  </Accordion>
+  <Accordion title="跳过">
+    保持身份验证未配置。
+  </Accordion>
+</AccordionGroup>
+
+模型行为：
+
+- 从检测到的选项中选择默认模型，或手动输入提供商和模型。
+- 向导会执行模型检查，并在配置的模型未知或缺少身份验证时发出警告。
+
+凭证和配置档案路径：
+
+- OAuth 凭证：`~/.quantumclaw/credentials/oauth.json`
+- Auth profile（API 密钥 + OAuth）：`~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`
+
+凭证存储模式：
+
+- 默认新手引导行为会将 API 密钥作为明文值持久化到 auth profile 中。
+- `--secret-input-mode ref` 会启用引用模式，而不是明文密钥存储。
+  在交互式设置中，你可以选择：
+  - 环境变量引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）
+  - 已配置提供商引用（`file` 或 `exec`），带提供商别名 + id
+- 交互式引用模式会在保存前运行快速预检验证。
+  - 环境变量引用：验证变量名 + 当前新手引导环境中的非空值。
+  - 提供商引用：验证提供商配置并解析所请求的 id。
+  - 如果预检失败，新手引导会显示错误并让你重试。
+- 在非交互式模式下，`--secret-input-mode ref` 仅支持由环境变量支持的引用。
+  - 在新手引导进程环境中设置提供商环境变量。
+  - 内联密钥标志（例如 `--openai-api-key`）要求设置该环境变量；否则新手引导会快速失败。
+  - 对于自定义提供商，非交互式 `ref` 模式会将 `models.providers.<id>.apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
+  - 在这种自定义提供商场景下，`--custom-api-key` 要求设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。
+- Gateway 网关身份验证凭证在交互式设置中支持明文和 SecretRef 选项：
+  - 令牌模式：**生成/存储明文令牌**（默认）或 **使用 SecretRef**。
+  - 密码模式：明文或 SecretRef。
+- 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
+- 现有的明文设置会继续保持不变并正常工作。
+
+<Note>
+无头和服务器提示：在有浏览器的机器上完成 OAuth，然后复制
+`~/.quantumclaw/credentials/oauth.json`（或 `$QUANTUMCLAW_STATE_DIR/credentials/oauth.json`）
+到 Gateway 网关主机。
+</Note>
+
+## 输出和内部机制
+
+`~/.quantumclaw/quantumclaw.json` 中的典型字段：
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
+- `tools.profile`（本地新手引导在未设置时默认设为 `"coding"`；现有显式值会保留）
+- `gateway.*`（模式、绑定、身份验证、tailscale）
+- `session.dmScope`（本地新手引导在未设置时默认设为 `per-channel-peer`；现有显式值会保留）
+- `channels.telegram.botToken`、`channels.discord.token`、`channels.signal.*`、`channels.imessage.*`
+- 当你在提示中选择加入时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（如果可能，名称会解析为 ID）
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`quantumclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
+
+WhatsApp 凭证位于 `~/.quantumclaw/credentials/whatsapp/<accountId>/`。
+会话存储在 `~/.quantumclaw/agents/<agentId>/sessions/` 下。
+
+<Note>
+某些渠道以插件形式交付。在设置期间选择这些渠道时，向导
+会先提示安装插件（npm 或本地路径），然后再进行渠道配置。
+</Note>
+
+Gateway 网关向导 RPC：
+
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+客户端（macOS 应用和控制 UI）可以在不重新实现新手引导逻辑的情况下渲染步骤。
+
+Signal 设置行为：
+
+- 下载适当的发布资源
+- 将其存储在 `~/.quantumclaw/tools/signal-cli/<version>/`
+- 在配置中写入 `channels.signal.cliPath`
+- JVM 构建需要 Java 21
+- 在可用时使用原生构建
+- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 signal-cli 流程
+
+## 相关文档
+
+- 新手引导中心：[设置向导（CLI）](/start/wizard)
+- 自动化和脚本：[CLI 自动化](/start/wizard-cli-automation)
+- 命令参考：[`quantumclaw onboard`](/cli/onboard)

package/docs/zh-CN/start/wizard.md

@@ -0,0 +1,132 @@
+---
+read_when:
+  - 运行或配置 CLI 新手引导
+  - 设置一台新机器
+sidebarTitle: "Onboarding: CLI"
+summary: CLI 新手引导：用于 Gateway 网关、工作区、渠道和 Skills 的引导式设置
+title: CLI 新手引导
+x-i18n:
+  generated_at: "2026-03-16T06:28:38Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 99fd87dddd78798eb0087ad9433e5a32de2af110b6e65ee351b1a194a11c7df3
+  source_path: start/wizard.md
+  workflow: 15
+---
+
+# CLI 新手引导
+
+CLI 新手引导是在 macOS、
+Linux 或 Windows（通过 WSL2；强烈推荐）上设置 QuantumClaw 的**推荐**方式。
+它可在一次引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills
+和工作区默认值。
+
+```bash
+quantumclaw onboard
+```
+
+<Info>
+最快的首次聊天方式：打开 Control UI（无需设置渠道）。运行
+`quantumclaw dashboard` 并在浏览器中聊天。文档：[Dashboard](/web/dashboard)。
+</Info>
+
+若要稍后重新配置：
+
+```bash
+quantumclaw configure
+quantumclaw agents add <name>
+```
+
+<Note>
+`--json` 并不意味着非交互模式。对于脚本，请使用 `--non-interactive`。
+</Note>
+
+<Tip>
+CLI 新手引导包含一个 web search 步骤，你可以选择一个提供商
+（Perplexity、Brave、Gemini、Grok 或 Kimi），并粘贴你的 API 密钥，以便智能体
+可以使用 `web_search`。你也可以稍后通过
+`quantumclaw configure --section web` 进行配置。文档：[Web 工具](/tools/web)。
+</Tip>
+
+## 快速开始与高级模式
+
+新手引导开始时会让你选择**快速开始**（默认值）或**高级模式**（完全控制）。
+
+<Tabs>
+  <Tab title="快速开始（默认值）">
+    - 本地网关（loopback）
+    - 默认工作区（或现有工作区）
+    - Gateway 网关端口 **18789**
+    - Gateway 网关认证 **Token**（即使在 loopback 上也会自动生成）
+    - 新本地设置的默认工具策略：`tools.profile: "coding"`（会保留现有显式配置文件）
+    - 私信隔离默认值：本地新手引导会在未设置时写入 `session.dmScope: "per-channel-peer"`。详情见：[CLI 设置参考](/start/wizard-cli-reference#outputs-and-internals)
+    - Tailscale 暴露 **关闭**
+    - Telegram + WhatsApp 私信默认使用 **allowlist**（系统会提示你输入电话号码）
+  </Tab>
+  <Tab title="高级模式（完全控制）">
+    - 暴露每一个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。
+  </Tab>
+</Tabs>
+
+## 新手引导会配置什么
+
+**本地模式（默认）**会引导你完成以下步骤：
+
+1. **模型/认证** —— 选择任意受支持的提供商/认证流程（API 密钥、OAuth 或 setup-token），包括自定义提供商
+   （兼容 OpenAI、兼容 Anthropic，或未知自动检测）。选择一个默认模型。
+   安全说明：如果这个智能体将运行工具或处理 webhook/hooks 内容，请优先选择当前可用的最强最新一代模型，并保持严格的工具策略。较弱/较旧的层级更容易被 prompt 注入。
+   对于非交互式运行，`--secret-input-mode ref` 会在认证配置文件中存储基于环境变量的引用，而不是明文 API 密钥值。
+   在非交互式 `ref` 模式下，必须设置提供商环境变量；如果传入内联密钥标志但缺少该环境变量，则会快速失败。
+   在交互式运行中，选择 secret reference 模式后，你可以指向环境变量或已配置的 provider ref（`file` 或 `exec`），并在保存前进行快速预检校验。
+2. **工作区** —— 智能体文件的位置（默认 `~/.quantumclaw/workspace`）。会植入引导文件。
+3. **Gateway 网关** —— 端口、绑定地址、认证模式、Tailscale 暴露。
+   在交互式 token 模式中，你可以选择默认的明文 token 存储，或选择启用 SecretRef。
+   非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
+4. **渠道** —— WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
+5. **守护进程** —— 安装 LaunchAgent（macOS）或 systemd 用户单元（Linux/WSL2）。
+   如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将已解析的 token 持久化到监督服务的环境元数据中。
+   如果 token 认证需要 token，而已配置的 token SecretRef 无法解析，守护进程安装会被阻止，并提供可执行的指导。
+   如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，守护进程安装会被阻止，直到显式设置 mode。
+6. **健康检查** —— 启动 Gateway 网关并验证其正在运行。
+7. **Skills** —— 安装推荐的 Skills 和可选依赖项。
+
+<Note>
+重新运行新手引导**不会**清除任何内容，除非你显式选择 **Reset**（或传入 `--reset`）。
+CLI `--reset` 默认会重置配置、凭证和会话；如需包含工作区，请使用 `--reset-scope full`。
+如果配置无效或包含旧版键，新手引导会先要求你运行 `quantumclaw doctor`。
+</Note>
+
+**远程模式**只会配置本地客户端以连接到其他地方的 Gateway 网关。
+它**不会**在远程主机上安装或更改任何内容。
+
+## 添加另一个智能体
+
+使用 `quantumclaw agents add <name>` 创建一个单独的智能体，它拥有自己的工作区、
+会话和认证配置文件。不带 `--workspace` 运行会启动新手引导。
+
+它会设置：
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+说明：
+
+- 默认工作区遵循 `~/.quantumclaw/workspace-<agentId>`。
+- 添加 `bindings` 以路由入站消息（新手引导可以完成这项操作）。
+- 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。
+
+## 完整参考
+
+有关详细的分步骤拆解和配置输出，请参见
+[CLI 设置参考](/start/wizard-cli-reference)。
+有关非交互式示例，请参见 [CLI 自动化](/start/wizard-cli-automation)。
+有关更深入的技术参考（包括 RPC 细节），请参见
+[新手引导参考](/reference/wizard)。
+
+## 相关文档
+
+- CLI 命令参考：[`quantumclaw onboard`](/cli/onboard)
+- 新手引导概览：[Onboarding Overview](/start/onboarding-overview)
+- macOS 应用新手引导：[新手引导](/start/onboarding)
+- 智能体首次运行仪式：[智能体引导](/start/bootstrapping)

package/docs/zh-CN/tools/agent-send.md

@@ -0,0 +1,59 @@
+---
+read_when:
+  - 添加或修改智能体 CLI 入口点
+summary: 直接 `quantumclaw agent` CLI 运行（带可选投递）
+title: Agent Send
+x-i18n:
+  generated_at: "2026-02-03T07:54:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a84d6a304333eebe155da2bf24cf5fc0482022a0a48ab34aa1465cd6e667022d
+  source_path: tools/agent-send.md
+  workflow: 15
+---
+
+# `quantumclaw agent`（直接智能体运行）
+
+`quantumclaw agent` 运行单个智能体回合，无需入站聊天消息。
+默认情况下它**通过 Gateway 网关**运行；添加 `--local` 以强制在当前机器上使用嵌入式运行时。
+
+## 行为
+
+- 必需：`--message <text>`
+- 会话选择：
+  - `--to <dest>` 派生会话键（群组/频道目标保持隔离；直接聊天折叠到 `main`），**或**
+  - `--session-id <id>` 通过 ID 重用现有会话，**或**
+  - `--agent <id>` 直接定位已配置的智能体（使用该智能体的 `main` 会话键）
+- 运行与正常入站回复相同的嵌入式智能体运行时。
+- 思考/详细标志持久化到会话存储中。
+- 输出：
+  - 默认：打印回复文本（加上 `MEDIA:<url>` 行）
+  - `--json`：打印结构化负载 + 元数据
+- 可选使用 `--deliver` + `--channel` 将回复投递回渠道（目标格式与 `quantumclaw message --target` 匹配）。
+- 使用 `--reply-channel`/`--reply-to`/`--reply-account` 覆盖投递而不更改会话。
+
+如果 Gateway 网关不可达，CLI 会**回退**到嵌入式本地运行。
+
+## 示例
+
+```bash
+quantumclaw agent --to +15555550123 --message "status update"
+quantumclaw agent --agent ops --message "Summarize logs"
+quantumclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
+quantumclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
+quantumclaw agent --to +15555550123 --message "Summon reply" --deliver
+quantumclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+```
+
+## 标志
+
+- `--local`：本地运行（需要你的 shell 中有模型提供商 API 密钥）
+- `--deliver`：将回复发送到所选渠道
+- `--channel`：投递渠道（`whatsapp|telegram|discord|googlechat|slack|signal|imessage`，默认：`whatsapp`）
+- `--reply-to`：投递目标覆盖
+- `--reply-channel`：投递渠道覆盖
+- `--reply-account`：投递账户 ID 覆盖
+- `--thinking <off|minimal|low|medium|high|xhigh>`：持久化思考级别（仅限 GPT-5.2 + Codex 模型）
+- `--verbose <on|full|off>`：持久化详细级别
+- `--timeout <seconds>`：覆盖智能体超时
+- `--json`：输出结构化 JSON

package/docs/zh-CN/tools/apply-patch.md

@@ -0,0 +1,57 @@
+---
+read_when:
+  - 你需要跨多个文件进行结构化编辑
+  - 你想要记录或调试基于补丁的编辑
+summary: 使用 apply_patch 工具应用多文件补丁
+title: apply_patch 工具
+x-i18n:
+  generated_at: "2026-02-01T21:39:24Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8cec2b4ee3afa9105fc3dd1bc28a338917df129afc634ac83620a3347c46bcec
+  source_path: tools/apply-patch.md
+  workflow: 15
+---
+
+# apply_patch 工具
+
+使用结构化补丁格式应用文件更改。这非常适合多文件
+或多段编辑，在这些场景下单次 `edit` 调用会很脆弱。
+
+该工具接受一个 `input` 字符串，其中包含一个或多个文件操作：
+
+```
+*** Begin Patch
+*** Add File: path/to/file.txt
++line 1
++line 2
+*** Update File: src/app.ts
+@@
+-old line
++new line
+*** Delete File: obsolete.txt
+*** End Patch
+```
+
+## 参数
+
+- `input`（必需）：完整的补丁内容，包括 `*** Begin Patch` 和 `*** End Patch`。
+
+## 说明
+
+- 路径相对于工作区根目录解析。
+- 在 `*** Update File:` 段中使用 `*** Move to:` 可重命名文件。
+- 需要时使用 `*** End of File` 标记仅在文件末尾的插入。
+- 实验性功能，默认禁用。通过 `tools.exec.applyPatch.enabled` 启用。
+- 仅限 OpenAI（包括 OpenAI Codex）。可选通过
+  `tools.exec.applyPatch.allowModels` 按模型进行限制。
+- 配置仅在 `tools.exec` 下。
+
+## 示例
+
+```json
+{
+  "tool": "apply_patch",
+  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
+}
+```