@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/concepts/models.md

@@ -0,0 +1,225 @@
+---
+read_when:
+  - 添加或修改 models CLI（models list/set/scan/aliases/fallbacks）
+  - 更改模型回退行为或选择 UX
+  - 更新模型扫描探测（tools/images）
+summary: Models CLI：列出、设置、别名、回退、扫描、状态
+title: Models CLI
+x-i18n:
+  generated_at: "2026-03-16T06:22:01Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 26150aef638bc3375866dec736b98eac32384466a8ef2b0a471fb7ff7729b13c
+  source_path: concepts/models.md
+  workflow: 15
+---
+
+# Models CLI
+
+关于凭证配置轮换、冷却时间以及它们如何与回退交互，请参阅 [/concepts/model-failover](/concepts/model-failover)。
+快速提供商概览 + 示例：[/concepts/model-providers](/concepts/model-providers)。
+
+## 模型选择的工作方式
+
+QuantumClaw 按以下顺序选择模型：
+
+1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
+2. `agents.defaults.model.fallbacks` 中的 **回退模型**（按顺序）。
+3. **提供商凭证故障切换** 会在单个提供商内部发生，然后才会移动到下一个模型。
+
+相关内容：
+
+- `agents.defaults.models` 是 QuantumClaw 可使用的模型允许列表/目录（以及别名）。
+- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。
+- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定来覆盖 `agents.defaults.model`（见 [/concepts/multi-agent](/concepts/multi-agent)）。
+
+## 快速模型策略
+
+- 将你的主模型设置为你可用的、最新一代中最强的模型。
+- 对于对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
+- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
+
+## 设置向导（推荐）
+
+如果你不想手动编辑配置，请运行设置向导：
+
+```bash
+quantumclaw onboard
+```
+
+它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex)**
+订阅（OAuth）和 **Anthropic**（API key 或 `claude setup-token`）。
+
+## 配置键（概览）
+
+- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
+- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
+- `agents.defaults.models`（允许列表 + 别名 + 提供商参数）
+- `models.providers`（写入 `models.json` 的自定义提供商）
+
+模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化
+为 `zai/*`。
+
+提供商配置示例（包括 OpenCode）位于
+[/gateway/configuration](/gateway/configuration#opencode)。
+
+## “Model is not allowed”（以及为什么回复会停止）
+
+如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的 **允许列表**。当用户选择了不在该允许列表中的模型时，
+QuantumClaw 会返回：
+
+```
+Model "provider/model" is not allowed. Use /model to list available models.
+```
+
+这会在生成正常回复 **之前** 发生，因此消息可能会让人觉得
+它“没有响应”。修复方法是：
+
+- 将该模型添加到 `agents.defaults.models`，或者
+- 清除允许列表（移除 `agents.defaults.models`），或者
+- 从 `/model list` 中选择一个模型。
+
+允许列表示例配置：
+
+```json5
+{
+  agent: {
+    model: { primary: "anthropic/claude-sonnet-4-5" },
+    models: {
+      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
+      "anthropic/claude-opus-4-6": { alias: "Opus" },
+    },
+  },
+}
+```
+
+## 在聊天中切换模型（`/model`）
+
+你可以在不重启的情况下为当前会话切换模型：
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.2
+/model status
+```
+
+说明：
+
+- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
+- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。
+- `/model <#>` 会从该选择器中进行选择。
+- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。
+- 模型引用是通过按 **第一个** `/` 进行分割来解析的。输入 `/model <ref>` 时请使用 `provider/model`。
+- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
+- 如果你省略提供商，QuantumClaw 会将输入视为别名或 **默认提供商** 的模型（仅在模型 ID 中没有 `/` 时有效）。
+
+完整命令行为/配置： [Slash commands](/tools/slash-commands)。
+
+## CLI 命令
+
+```bash
+quantumclaw models list
+quantumclaw models status
+quantumclaw models set <provider/model>
+quantumclaw models set-image <provider/model>
+
+quantumclaw models aliases list
+quantumclaw models aliases add <alias> <provider/model>
+quantumclaw models aliases remove <alias>
+
+quantumclaw models fallbacks list
+quantumclaw models fallbacks add <provider/model>
+quantumclaw models fallbacks remove <provider/model>
+quantumclaw models fallbacks clear
+
+quantumclaw models image-fallbacks list
+quantumclaw models image-fallbacks add <provider/model>
+quantumclaw models image-fallbacks remove <provider/model>
+quantumclaw models image-fallbacks clear
+```
+
+`quantumclaw models`（无子命令）是 `models status` 的快捷方式。
+
+### `models list`
+
+默认显示已配置的模型。常用标志：
+
+- `--all`：完整目录
+- `--local`：仅本地提供商
+- `--provider <name>`：按提供商筛选
+- `--plain`：每行一个模型
+- `--json`：机器可读输出
+
+### `models status`
+
+显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态
+（默认会在 24 小时内到期时警告）。`--plain` 仅打印已解析的
+主模型。
+OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的
+提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。
+JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`
+（每个提供商的有效凭证）。
+自动化场景请使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。
+
+凭证选择取决于提供商/账号。对于始终在线的 Gateway 网关主机，API key 通常最可预测；也支持订阅 token 流程。
+
+示例（Anthropic setup-token）：
+
+```bash
+claude setup-token
+quantumclaw models status
+```
+
+## 扫描（OpenRouter 免费模型）
+
+`quantumclaw models scan` 会检查 OpenRouter 的 **免费模型目录**，并且可以
+选择性地探测模型对工具和图像的支持。
+
+关键标志：
+
+- `--no-probe`：跳过实时探测（仅元数据）
+- `--min-params <b>`：最小参数规模（十亿）
+- `--max-age-days <days>`：跳过较旧模型
+- `--provider <name>`：提供商前缀筛选
+- `--max-candidates <n>`：回退列表大小
+- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项
+- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项
+
+探测需要 OpenRouter API key（来自凭证配置文件或
+`OPENROUTER_API_KEY`）。如果没有 key，请使用 `--no-probe` 仅列出候选项。
+
+扫描结果按以下顺序排序：
+
+1. 图像支持
+2. 工具延迟
+3. 上下文大小
+4. 参数数量
+
+输入
+
+- OpenRouter `/models` 列表（筛选 `:free`）
+- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（见 [/environment](/help/environment)）
+- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
+- 探测控制：`--timeout`、`--concurrency`
+
+在 TTY 中运行时，你可以交互式选择回退模型。在非交互
+模式下，传入 `--yes` 以接受默认值。
+
+## 模型注册表（`models.json`）
+
+`models.providers` 中的自定义提供商会写入
+智能体目录下的 `models.json`（默认是 `~/.quantumclaw/agents/<agentId>/agent/models.json`）。默认会合并此文件，除非将 `models.mode` 设置为 `replace`。
+
+匹配提供商 ID 时的合并模式优先级：
+
+- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
+- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是 SecretRef 管理时才优先。
+- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）刷新，而不是持久化已解析的 secret。
+- 由 SecretRef 管理的提供商 header 值会从源标记（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）刷新。
+- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
+- 其他提供商字段会从配置和规范化后的目录数据中刷新。
+
+标记持久化以源为准：QuantumClaw 会根据活动源配置快照（预解析）写入标记，而不是根据运行时已解析的 secret 值写入。
+这适用于 QuantumClaw 重新生成 `models.json` 的所有情况，包括像 `quantumclaw agent` 这样的命令驱动路径。

package/docs/zh-CN/concepts/multi-agent.md

@@ -0,0 +1,372 @@
+---
+read_when: You want multiple isolated agents (workspaces + auth) in one gateway process.
+status: active
+summary: 多智能体路由：隔离的智能体、渠道账户和绑定
+title: 多智能体路由
+x-i18n:
+  generated_at: "2026-02-03T07:47:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1848266c632cd6c96ff99ea9eb9c17bbfe6d35fa1f90450853083e7c548d5324
+  source_path: concepts/multi-agent.md
+  workflow: 15
+---
+
+# 多智能体路由
+
+目标：多个*隔离的*智能体（独立的工作区 + `agentDir` + 会话），加上多个渠道账户（例如两个 WhatsApp）在一个运行的 Gateway 网关中。入站消息通过绑定路由到智能体。
+
+## 什么是"一个智能体"？
+
+一个**智能体**是一个完全独立作用域的大脑，拥有自己的：
+
+- **工作区**（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）。
+- **状态目录**（`agentDir`）用于认证配置文件、模型注册表和每智能体配置。
+- **会话存储**（聊天历史 + 路由状态）位于 `~/.quantumclaw/agents/<agentId>/sessions` 下。
+
+认证配置文件是**每智能体独立的**。每个智能体从自己的位置读取：
+
+```
+~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json
+```
+
+主智能体凭证**不会**自动共享。切勿在智能体之间重用 `agentDir`（这会导致认证/会话冲突）。如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir`。
+
+Skills 通过每个工作区的 `skills/` 文件夹实现每智能体独立，共享的 Skills 可从 `~/.quantumclaw/skills` 获取。参见 [Skills：每智能体 vs 共享](/tools/skills#per-agent-vs-shared-skills)。
+
+Gateway 网关可以托管**一个智能体**（默认）或**多个智能体**并行。
+
+**工作区注意事项：** 每个智能体的工作区是**默认 cwd**，而不是硬性沙箱。相对路径在工作区内解析，但绝对路径可以访问主机的其他位置，除非启用了沙箱隔离。参见 [沙箱隔离](/gateway/sandboxing)。
+
+## 路径（快速映射）
+
+- 配置：`~/.quantumclaw/quantumclaw.json`（或 `QUANTUMCLAW_CONFIG_PATH`）
+- 状态目录：`~/.quantumclaw`（或 `QUANTUMCLAW_STATE_DIR`）
+- 工作区：`~/.quantumclaw/workspace`（或 `~/.quantumclaw/workspace-<agentId>`）
+- 智能体目录：`~/.quantumclaw/agents/<agentId>/agent`（或 `agents.list[].agentDir`）
+- 会话：`~/.quantumclaw/agents/<agentId>/sessions`
+
+### 单智能体模式（默认）
+
+如果你什么都不做，QuantumClaw 运行单个智能体：
+
+- `agentId` 默认为 **`main`**。
+- 会话键为 `agent:main:<mainKey>`。
+- 工作区默认为 `~/.quantumclaw/workspace`（或当设置了 `QUANTUMCLAW_PROFILE` 时为 `~/.quantumclaw/workspace-<profile>`）。
+- 状态默认为 `~/.quantumclaw/agents/main/agent`。
+
+## 智能体助手
+
+使用智能体向导添加新的隔离智能体：
+
+```bash
+quantumclaw agents add work
+```
+
+然后添加 `bindings`（或让向导完成）来路由入站消息。
+
+验证：
+
+```bash
+quantumclaw agents list --bindings
+```
+
+## 多个智能体 = 多个人、多种人格
+
+使用**多个智能体**，每个 `agentId` 成为一个**完全隔离的人格**：
+
+- **不同的电话号码/账户**（每渠道 `accountId`）。
+- **不同的人格**（每智能体工作区文件如 `AGENTS.md` 和 `SOUL.md`）。
+- **独立的认证 + 会话**（除非明确启用，否则无交叉通信）。
+
+这让**多个人**共享一个 Gateway 网关服务器，同时保持他们的 AI"大脑"和数据隔离。
+
+## 一个 WhatsApp 号码，多个人（私信分割）
+
+你可以将**不同的 WhatsApp 私信**路由到不同的智能体，同时保持**一个 WhatsApp 账户**。使用 `peer.kind: "dm"` 匹配发送者 E.164（如 `+15551234567`）。回复仍然来自同一个 WhatsApp 号码（无每智能体发送者身份）。
+
+重要细节：直接聊天折叠到智能体的**主会话键**，因此真正的隔离需要**每人一个智能体**。
+
+示例：
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "alex", workspace: "~/.quantumclaw/workspace-alex" },
+      { id: "mia", workspace: "~/.quantumclaw/workspace-mia" },
+    ],
+  },
+  bindings: [
+    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
+    { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
+  ],
+  channels: {
+    whatsapp: {
+      dmPolicy: "allowlist",
+      allowFrom: ["+15551230001", "+15551230002"],
+    },
+  },
+}
+```
+
+注意事项：
+
+- 私信访问控制是**每 WhatsApp 账户全局的**（配对/允许列表），而不是每智能体。
+- 对于共享群组，将群组绑定到一个智能体或使用 [广播群组](/channels/broadcast-groups)。
+
+## 路由规则（消息如何选择智能体）
+
+绑定是**确定性的**，**最具体的优先**：
+
+1. `peer` 匹配（精确私信/群组/频道 id）
+2. `guildId`（Discord）
+3. `teamId`（Slack）
+4. 渠道的 `accountId` 匹配
+5. 渠道级匹配（`accountId: "*"`）
+6. 回退到默认智能体（`agents.list[].default`，否则列表中的第一个条目，默认：`main`）
+
+## 多账户/电话号码
+
+支持**多账户**的渠道（如 WhatsApp）使用 `accountId` 来识别每个登录。每个 `accountId` 可以路由到不同的智能体，因此一个服务器可以托管多个电话号码而不混合会话。
+
+## 概念
+
+- `agentId`：一个"大脑"（工作区、每智能体认证、每智能体会话存储）。
+- `accountId`：一个渠道账户实例（例如 WhatsApp 账户 `"personal"` vs `"biz"`）。
+- `binding`：通过 `(channel, accountId, peer)` 以及可选的 guild/team id 将入站消息路由到 `agentId`。
+- 直接聊天折叠到 `agent:<agentId>:<mainKey>`（每智能体"主"；`session.mainKey`）。
+
+## 示例：两个 WhatsApp → 两个智能体
+
+`~/.quantumclaw/quantumclaw.json`（JSON5）：
+
+```js
+{
+  agents: {
+    list: [
+      {
+        id: "home",
+        default: true,
+        name: "Home",
+        workspace: "~/.quantumclaw/workspace-home",
+        agentDir: "~/.quantumclaw/agents/home/agent",
+      },
+      {
+        id: "work",
+        name: "Work",
+        workspace: "~/.quantumclaw/workspace-work",
+        agentDir: "~/.quantumclaw/agents/work/agent",
+      },
+    ],
+  },
+
+  // 确定性路由：第一个匹配获胜（最具体的优先）。
+  bindings: [
+    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
+    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
+
+    // 可选的每对等方覆盖（示例：将特定群组发送到 work 智能体）。
+    {
+      agentId: "work",
+      match: {
+        channel: "whatsapp",
+        accountId: "personal",
+        peer: { kind: "group", id: "1203630...@g.us" },
+      },
+    },
+  ],
+
+  // 默认关闭：智能体到智能体的消息必须明确启用 + 加入允许列表。
+  tools: {
+    agentToAgent: {
+      enabled: false,
+      allow: ["home", "work"],
+    },
+  },
+
+  channels: {
+    whatsapp: {
+      accounts: {
+        personal: {
+          // 可选覆盖。默认：~/.quantumclaw/credentials/whatsapp/personal
+          // authDir: "~/.quantumclaw/credentials/whatsapp/personal",
+        },
+        biz: {
+          // 可选覆盖。默认：~/.quantumclaw/credentials/whatsapp/biz
+          // authDir: "~/.quantumclaw/credentials/whatsapp/biz",
+        },
+      },
+    },
+  },
+}
+```
+
+## 示例：WhatsApp 日常聊天 + Telegram 深度工作
+
+按渠道分割：将 WhatsApp 路由到快速日常智能体，Telegram 路由到 Opus 智能体。
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "chat",
+        name: "Everyday",
+        workspace: "~/.quantumclaw/workspace-chat",
+        model: "anthropic/claude-sonnet-4-5",
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/.quantumclaw/workspace-opus",
+        model: "anthropic/claude-opus-4-5",
+      },
+    ],
+  },
+  bindings: [
+    { agentId: "chat", match: { channel: "whatsapp" } },
+    { agentId: "opus", match: { channel: "telegram" } },
+  ],
+}
+```
+
+注意事项：
+
+- 如果你有一个渠道的多个账户，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
+- 要将单个私信/群组路由到 Opus 而保持其余在 chat 上，请为该对等方添加 `match.peer` 绑定；对等方匹配始终优先于渠道级规则。
+
+## 示例：同一渠道，一个对等方到 Opus
+
+保持 WhatsApp 在快速智能体上，但将一个私信路由到 Opus：
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "chat",
+        name: "Everyday",
+        workspace: "~/.quantumclaw/workspace-chat",
+        model: "anthropic/claude-sonnet-4-5",
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/.quantumclaw/workspace-opus",
+        model: "anthropic/claude-opus-4-5",
+      },
+    ],
+  },
+  bindings: [
+    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
+    { agentId: "chat", match: { channel: "whatsapp" } },
+  ],
+}
+```
+
+对等方绑定始终获胜，因此将它们放在渠道级规则之上。
+
+## 绑定到 WhatsApp 群组的家庭智能体
+
+将专用家庭智能体绑定到单个 WhatsApp 群组，使用提及限制和更严格的工具策略：
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "family",
+        name: "Family",
+        workspace: "~/.quantumclaw/workspace-family",
+        identity: { name: "Family Bot" },
+        groupChat: {
+          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
+        },
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+        },
+        tools: {
+          allow: [
+            "exec",
+            "read",
+            "sessions_list",
+            "sessions_history",
+            "sessions_send",
+            "sessions_spawn",
+            "session_status",
+          ],
+          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "family",
+      match: {
+        channel: "whatsapp",
+        peer: { kind: "group", id: "120363999999999999@g.us" },
+      },
+    },
+  ],
+}
+```
+
+注意事项：
+
+- 工具允许/拒绝列表是**工具**，不是 Skills。如果 skill 需要运行二进制文件，请确保 `exec` 被允许且二进制文件存在于沙箱中。
+- 对于更严格的限制，设置 `agents.list[].groupChat.mentionPatterns` 并为渠道保持群组允许列表启用。
+
+## 每智能体沙箱和工具配置
+
+从 v2026.1.6 开始，每个智能体可以有自己的沙箱和工具限制：
+
+```js
+{
+  agents: {
+    list: [
+      {
+        id: "personal",
+        workspace: "~/.quantumclaw/workspace-personal",
+        sandbox: {
+          mode: "off",  // 个人智能体无沙箱
+        },
+        // 无工具限制 - 所有工具可用
+      },
+      {
+        id: "family",
+        workspace: "~/.quantumclaw/workspace-family",
+        sandbox: {
+          mode: "all",     // 始终沙箱隔离
+          scope: "agent",  // 每智能体一个容器
+          docker: {
+            // 容器创建后的可选一次性设置
+            setupCommand: "apt-get update && apt-get install -y git curl",
+          },
+        },
+        tools: {
+          allow: ["read"],                    // 仅 read 工具
+          deny: ["exec", "write", "edit", "apply_patch"],    // 拒绝其他
+        },
+      },
+    ],
+  },
+}
+```
+
+注意：`setupCommand` 位于 `sandbox.docker` 下，在容器创建时运行一次。
+当解析的 scope 为 `"shared"` 时，每智能体 `sandbox.docker.*` 覆盖会被忽略。
+
+**好处：**
+
+- **安全隔离**：限制不受信任智能体的工具
+- **资源控制**：沙箱隔离特定智能体同时保持其他智能体在主机上
+- **灵活策略**：每智能体不同的权限
+
+注意：`tools.elevated` 是**全局的**且基于发送者；不能按智能体配置。
+如果你需要每智能体边界，使用 `agents.list[].tools` 拒绝 `exec`。
+对于群组定向，使用 `agents.list[].groupChat.mentionPatterns` 使 @提及清晰地映射到目标智能体。
+
+参见 [多智能体沙箱和工具](/tools/multi-agent-sandbox-tools) 了解详细示例。