@termix-it/cryptoclaw 1.0.0

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`）用于认证配置文件、模型注册表和每智能体配置。
+- **会话存储**（聊天历史 + 路由状态）位于 `~/.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 网关可以托管**一个智能体**（默认）或**多个智能体**并行。
+
+**工作区注意事项：** 每个智能体的工作区是**默认 cwd**，而不是硬性沙箱。相对路径在工作区内解析，但绝对路径可以访问主机的其他位置，除非启用了沙箱隔离。参见 [沙箱隔离](/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 账户**。使用 `peer.kind: "dm"` 匹配发送者 E.164（如 `+15551234567`）。回复仍然来自同一个 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。如果 skill 需要运行二进制文件，请确保 `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 网关 WS 连接或系统事件信标
+summary: OpenClaw 在线状态条目如何生成、合并和显示
+title: 在线状态
+x-i18n:
+  generated_at: "2026-02-03T07:46:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c752c76a880878fed673d656db88beb5dbdeefff2491985127ad791521f97d00
+  source_path: concepts/presence.md
+  workflow: 15
+---
+
+# 在线状态
+
+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 连接
+
+每个 WS 客户端都以 `connect` 请求开始。在成功握手后，Gateway 网关为该连接更新插入一个在线状态条目。
+
+#### 为什么一次性 CLI 命令不会显示
+
+CLI 经常为短暂的一次性命令进行连接。为避免实例列表被刷屏，`client.mode === "cli"` **不会**被转换为在线状态条目。
+
+### 3）`system-event` 信标
+
+客户端可以通过 `system-event` 方法发送更丰富的周期性信标。mac 应用使用此方法报告主机名、IP 和 `lastInputSeconds`。
+
+### 4）节点连接（role: node）
+
+当节点通过 Gateway 网关 WebSocket 以 `role: node` 连接时，Gateway 网关为该节点更新插入一个在线状态条目（与其他 WS 客户端流程相同）。
+
+## 合并 + 去重规则（为什么 `instanceId` 很重要）
+
+在线状态条目存储在单个内存映射中：
+
+- 条目以**在线状态键**为索引。
+- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），它在重启后仍然有效。
+- 键不区分大小写。
+
+如果客户端在没有稳定 `instanceId` 的情况下重新连接，它可能会显示为**重复**行。
+
+## TTL 和有界大小
+
+在线状态是有意设计为短暂的：
+
+- **TTL：** 超过 5 分钟的条目会被修剪
+- **最大条目数：** 200（最旧的优先删除）
+
+这使列表保持新鲜并避免无限制的内存增长。
+
+## 远程/隧道注意事项（回环 IP）
+
+当客户端通过 SSH 隧道/本地端口转发连接时，Gateway 网关可能会看到远程地址为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，回环远程地址会被忽略。
+
+## 消费者
+
+### macOS 实例标签页
+
+macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间应用一个小的状态指示器（活跃/空闲/过期）。
+
+## 调试技巧
+
+- 要查看原始列表，对 Gateway 网关调用 `system-presence`。
+- 如果你看到重复项：
+  - 确认客户端在握手中发送稳定的 `client.instanceId`
+  - 确认周期性信标使用相同的 `instanceId`
+  - 检查连接派生的条目是否缺少 `instanceId`（这种情况下重复是预期的）