@gguf/claw 2026.2.1 → 2026.2.2

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

@@ -0,0 +1,369 @@
+---
+read_when: 你希望在一个 Gateway网关进程中运行多个隔离的智能体（工作区 + 认证）。
+status: active
+summary: 多智能体路由：隔离的智能体、渠道账户和绑定
+title: 多智能体路由
+x-i18n:
+  generated_at: "2026-02-01T20:23:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1848266c632cd6c96ff99ea9eb9c17bbfe6d35fa1f90450853083e7c548d5324
+  source_path: concepts/multi-agent.md
+  workflow: 14
+---
+
+# 多智能体路由
+
+目标：在一个运行中的 Gateway网关中托管多个*隔离的*智能体（独立的工作区 + `agentDir` + 会话），以及多个渠道账户（例如两个 WhatsApp）。入站消息通过绑定路由到对应的智能体。
+
+## 什么是"一个智能体"？
+
+一个**智能体**是一个完全独立作用域的大脑，拥有自己的：
+
+- **工作区**（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）。
+- **状态目录**（`agentDir`），用于存储认证配置文件、模型注册表和按智能体配置。
+- **会话存储**（聊天历史 + 路由状态），位于 `~/.openclaw/agents/<agentId>/sessions`。
+
+认证配置文件是**按智能体隔离的**。每个智能体从自己的目录读取：
+
+```
+~/.openclaw/agents/<agentId>/agent/auth-profiles.json
+```
+
+主智能体的凭证**不会**自动共享。切勿在智能体之间复用 `agentDir`（会导致认证/会话冲突）。如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。
+
+Skills 通过每个工作区的 `skills/` 文件夹按智能体隔离，共享 Skills 可从 `~/.openclaw/skills` 获取。参阅[Skills：按智能体 vs 共享](/tools/skills#per-agent-vs-shared-skills)。
+
+Gateway网关可以托管**一个智能体**（默认）或**多个智能体**并行运行。
+
+**工作区说明：** 每个智能体的工作区是**默认工作目录**，而非严格的沙箱。相对路径在工作区内解析，但绝对路径可以访问主机上的其他位置，除非启用了沙箱。参阅[沙箱](/gateway/sandboxing)。
+
+## 路径（速查）
+
+- 配置文件：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
+- 状态目录：`~/.openclaw`（或 `OPENCLAW_STATE_DIR`）
+- 工作区：`~/.openclaw/workspace`（或 `~/.openclaw/workspace-<agentId>`）
+- 智能体目录：`~/.openclaw/agents/<agentId>/agent`（或 `agents.list[].agentDir`）
+- 会话：`~/.openclaw/agents/<agentId>/sessions`
+
+### 单智能体模式（默认）
+
+如果你不做任何配置，OpenClaw 会运行单个智能体：
+
+- `agentId` 默认为 **`main`**。
+- 会话键格式为 `agent:main:<mainKey>`。
+- 工作区默认为 `~/.openclaw/workspace`（设置了 `OPENCLAW_PROFILE` 时为 `~/.openclaw/workspace-<profile>`）。
+- 状态默认为 `~/.openclaw/agents/main/agent`。
+
+## 智能体助手
+
+使用智能体向导添加新的隔离智能体：
+
+```bash
+openclaw agents add work
+```
+
+然后添加 `bindings`（或让向导完成）来路由入站消息。
+
+验证方式：
+
+```bash
+openclaw agents list --bindings
+```
+
+## 多智能体 = 多用户、多人设
+
+使用**多个智能体**时，每个 `agentId` 都成为一个**完全隔离的人设**：
+
+- **不同的手机号/账户**（按渠道 `accountId`）。
+- **不同的性格**（按智能体工作区文件，如 `AGENTS.md` 和 `SOUL.md`）。
+- **独立的认证 + 会话**（除非显式启用，否则无串扰）。
+
+这使得**多个用户**可以共享一台 Gateway网关服务器，同时保持各自的 AI "大脑"和数据隔离。
+
+## 一个 WhatsApp 号码，多个用户（私聊分流）
+
+你可以将**不同的 WhatsApp 私聊**路由到不同的智能体，同时使用**同一个 WhatsApp 账户**。通过发送者的 E.164 格式号码（如 `+15551234567`）配合 `peer.kind: "dm"` 进行匹配。回复仍然从同一个 WhatsApp 号码发出（没有按智能体的发送者身份）。
+
+重要细节：私聊会折叠到智能体的**主会话键**，因此真正的隔离需要**每人一个智能体**。
+
+示例：
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
+      { id: "mia", workspace: "~/.openclaw/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 账户全局的**（配对/白名单），而非按智能体。
+- 对于共享群组，将群组绑定到一个智能体或使用[广播群组](/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 → 两个智能体
+
+`~/.openclaw/openclaw.json`（JSON5）：
+
+```js
+{
+  agents: {
+    list: [
+      {
+        id: "home",
+        default: true,
+        name: "Home",
+        workspace: "~/.openclaw/workspace-home",
+        agentDir: "~/.openclaw/agents/home/agent",
+      },
+      {
+        id: "work",
+        name: "Work",
+        workspace: "~/.openclaw/workspace-work",
+        agentDir: "~/.openclaw/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: {
+          // 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/personal
+          // authDir: "~/.openclaw/credentials/whatsapp/personal",
+        },
+        biz: {
+          // 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/biz
+          // authDir: "~/.openclaw/credentials/whatsapp/biz",
+        },
+      },
+    },
+  },
+}
+```
+
+## 示例：WhatsApp 日常聊天 + Telegram 深度工作
+
+按渠道分流：将 WhatsApp 路由到快速日常智能体，将 Telegram 路由到 Opus 智能体。
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "chat",
+        name: "Everyday",
+        workspace: "~/.openclaw/workspace-chat",
+        model: "anthropic/claude-sonnet-4-5",
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/.openclaw/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: "~/.openclaw/workspace-chat",
+        model: "anthropic/claude-sonnet-4-5",
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/.openclaw/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: "~/.openclaw/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。如果某个 Skills 需要运行二进制文件，请确保允许 `exec` 并且该二进制文件存在于沙箱中。
+- 要实现更严格的控制，请设置 `agents.list[].groupChat.mentionPatterns` 并为渠道启用群组白名单。
+
+## 按智能体的沙箱和工具配置
+
+从 v2026.1.6 开始，每个智能体可以有自己的沙箱和工具限制：
+
+```js
+{
+  agents: {
+    list: [
+      {
+        id: "personal",
+        workspace: "~/.openclaw/workspace-personal",
+        sandbox: {
+          mode: "off",  // 个人智能体不使用沙箱
+        },
+        // 无工具限制 - 所有工具可用
+      },
+      {
+        id: "family",
+        workspace: "~/.openclaw/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`，以便 @提及能准确映射到目标智能体。
+
+参阅[多智能体沙箱与工具](/multi-agent-sandbox-tools)获取详细示例。

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

@@ -0,0 +1,151 @@
+---
+read_when:
+  - 你想全面了解 OpenClaw 的 OAuth 流程
+  - 你遇到了令牌失效/登出问题
+  - 你想了解 setup-token 或 OAuth 认证流程
+  - 你想使用多账户或配置文件路由
+summary: OpenClaw 中的 OAuth：令牌交换、存储和多账户模式
+title: OAuth
+x-i18n:
+  generated_at: "2026-02-01T20:23:29Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: af714bdadc4a89295a18da1eba5f5b857c8d533ebabe9b0758b722fe60c36124
+  source_path: concepts/oauth.md
+  workflow: 14
+---
+
+# OAuth
+
+OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。本页说明：
+
+- OAuth **令牌交换**的工作原理（PKCE）
+- 令牌**存储**在哪里（以及原因）
+- 如何处理**多账户**（配置文件 + 按会话覆盖）
+
+OpenClaw 还支持**提供商插件**，它们自带 OAuth 或 API 密钥流程。通过以下命令运行：
+
+```bash
+openclaw models auth login --provider <id>
+```
+
+## 令牌汇聚点（为什么需要它）
+
+OAuth 提供商通常在登录/刷新流程中发放**新的刷新令牌**。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。
+
+实际症状：
+
+- 你通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出"
+
+为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌汇聚点**：
+
+- 运行时从**同一个位置**读取凭据
+- 我们可以保留多个配置文件并确定性地路由它们
+
+## 存储（令牌存放位置）
+
+密钥按**智能体**存储：
+
+- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- 运行时缓存（自动管理；请勿编辑）：`~/.openclaw/agents/<agentId>/agent/auth.json`
+
+仅用于导入的旧版文件（仍然支持，但不是主存储）：
+
+- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）
+
+以上所有路径也遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
+
+## Anthropic setup-token（订阅认证）
+
+在任意机器上运行 `claude setup-token`，然后将其粘贴到 OpenClaw 中：
+
+```bash
+openclaw models auth setup-token --provider anthropic
+```
+
+如果你在其他地方生成了令牌，可以手动粘贴：
+
+```bash
+openclaw models auth paste-token --provider anthropic
+```
+
+验证：
+
+```bash
+openclaw models status
+```
+
+## OAuth 交换（登录工作原理）
+
+OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并集成到向导/命令中。
+
+### Anthropic（Claude Pro/Max）setup-token
+
+流程概要：
+
+1. 运行 `claude setup-token`
+2. 将令牌粘贴到 OpenClaw
+3. 作为令牌认证配置文件存储（无刷新）
+
+向导路径为 `openclaw onboard` → 认证选择 `setup-token`（Anthropic）。
+
+### OpenAI Codex（ChatGPT OAuth）
+
+流程概要（PKCE）：
+
+1. 生成 PKCE 验证器/质询 + 随机 `state`
+2. 打开 `https://auth.openai.com/oauth/authorize?...`
+3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
+4. 如果回调无法绑定（或你在远程/无头环境中），手动粘贴重定向 URL/代码
+5. 在 `https://auth.openai.com/oauth/token` 进行交换
+6. 从访问令牌中提取 `accountId` 并存储 `{ access, refresh, expires, accountId }`
+
+向导路径为 `openclaw onboard` → 认证选择 `openai-codex`。
+
+## 刷新 + 过期
+
+配置文件存储 `expires` 时间戳。
+
+运行时：
+
+- 如果 `expires` 在未来 → 使用已存储的访问令牌
+- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
+
+刷新流程是自动的；你通常不需要手动管理令牌。
+
+## 多账户（配置文件）+ 路由
+
+两种模式：
+
+### 1）推荐：独立智能体
+
+如果你希望"个人"和"工作"永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：
+
+```bash
+openclaw agents add work
+openclaw agents add personal
+```
+
+然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
+
+### 2）高级：单个智能体中的多个配置文件
+
+`auth-profiles.json` 支持同一提供商的多个配置文件 ID。
+
+选择使用哪个配置文件：
+
+- 通过配置顺序全局设置（`auth.order`）
+- 通过 `/model ...@<profileId>` 按会话设置
+
+示例（会话覆盖）：
+
+- `/model Opus@anthropic:work`
+
+如何查看存在哪些配置文件 ID：
+
+- `openclaw channels list --json`（显示 `auth[]`）
+
+相关文档：
+
+- [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
+- [/tools/slash-commands](/tools/slash-commands)（命令界面）

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

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 调试实例选项卡
+  - 排查重复或过期的实例行
+  - 更改 Gateway网关 WebSocket 连接或系统事件信标
+summary: OpenClaw 在线状态条目的生成、合并与显示方式
+title: 在线状态
+x-i18n:
+  generated_at: "2026-02-01T20:23:31Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c752c76a880878fed673d656db88beb5dbdeefff2491985127ad791521f97d00
+  source_path: concepts/presence.md
+  workflow: 14
+---
+
+# 在线状态
+
+OpenClaw 的"在线状态"是一个轻量级、尽力而为的视图，展示：
+
+- **Gateway网关** 自身，以及
+- **连接到 Gateway网关的客户端**（Mac 应用、WebChat、CLI 等）
+
+在线状态主要用于渲染 macOS 应用的**实例**选项卡，并为操作人员提供快速可视化。
+
+## 在线状态字段（显示内容）
+
+在线状态条目是结构化对象，包含以下字段：
+
+- `instanceId`（可选但强烈建议提供）：稳定的客户端标识（通常为 `connect.client.instanceId`）
+- `host`：人类可读的主机名
+- `ip`：尽力而为的 IP 地址
+- `version`：客户端版本字符串
+- `deviceFamily` / `modelIdentifier`：硬件提示信息
+- `mode`：`ui`、`webchat`、`cli`、`backend`、`probe`、`test`、`node`，...
+- `lastInputSeconds`："距上次用户输入的秒数"（如果已知）
+- `reason`：`self`、`connect`、`node-connected`、`periodic`，...
+- `ts`：最后更新时间戳（自纪元以来的毫秒数）
+
+## 生产者（在线状态的来源）
+
+在线状态条目由多个来源产生并进行**合并**。
+
+### 1）Gateway网关自身条目
+
+Gateway网关在启动时始终会创建一个"self"条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway网关主机。
+
+### 2）WebSocket 连接
+
+每个 WebSocket 客户端都以 `connect` 请求开始。握手成功后，Gateway网关会为该连接更新插入一个在线状态条目。
+
+#### 为什么一次性 CLI 命令不会显示
+
+CLI 通常只为短暂的一次性命令建立连接。为避免实例列表被频繁刷新，`client.mode === "cli"` **不会**被转换为在线状态条目。
+
+### 3）`system-event` 信标
+
+客户端可以通过 `system-event` 方法发送更丰富的周期性信标。Mac 应用使用此机制报告主机名、IP 和 `lastInputSeconds`。
+
+### 4）节点连接（role: node）
+
+当节点通过 Gateway网关 WebSocket 以 `role: node` 连接时，Gateway网关会为该节点更新插入一个在线状态条目（与其他 WebSocket 客户端流程相同）。
+
+## 合并与去重规则（为什么 `instanceId` 很重要）
+
+在线状态条目存储在单个内存映射中：
+
+- 条目以**在线状态键**作为索引。
+- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），可在重启后保持不变。
+- 键不区分大小写。
+
+如果客户端在没有稳定 `instanceId` 的情况下重新连接，可能会显示为**重复**行。
+
+## TTL 和大小限制
+
+在线状态是有意设计为临时性的：
+
+- **TTL：**超过 5 分钟的条目将被清除
+- **最大条目数：**200（优先丢弃最旧的条目）
+
+这确保列表保持新鲜，避免无限制的内存增长。
+
+## 远程/隧道注意事项（local loopback IP）
+
+当客户端通过 SSH 隧道/本地端口转发连接时，Gateway网关可能会将远程地址识别为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，local loopback 远程地址会被忽略。
+
+## 消费者
+
+### macOS 实例选项卡
+
+macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间显示小型状态指示器（活跃/空闲/过期）。
+
+## 调试技巧
+
+- 要查看原始列表，请对 Gateway网关调用 `system-presence`。
+- 如果看到重复条目：
+  - 确认客户端在握手中发送了稳定的 `client.instanceId`
+  - 确认周期性信标使用相同的 `instanceId`
+  - 检查连接派生的条目是否缺少 `instanceId`（此时重复是预期行为）