@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/refactor/strict-config.md

@@ -0,0 +1,100 @@
+---
+read_when:
+  - 设计或实现配置验证行为时
+  - 处理配置迁移或 doctor 工作流时
+  - 处理插件配置 schema 或插件加载控制时
+summary: 严格配置验证 + 仅通过 doctor 执行迁移
+title: 严格配置验证
+x-i18n:
+  generated_at: "2026-02-01T21:36:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 5bc7174a67d2234e763f21330d8fe3afebc23b2e5c728a04abcc648b453a91cc
+  source_path: refactor/strict-config.md
+  workflow: 15
+---
+
+# 严格配置验证（仅通过 doctor 执行迁移）
+
+## 目标
+
+- **在所有层级（根级 + 嵌套级）拒绝未知配置键**。
+- **拒绝没有 schema 的插件配置**；不加载该插件。
+- **移除加载时的遗留自动迁移**；迁移仅通过 doctor 执行。
+- **启动时自动运行 doctor（dry-run 模式）**；如果配置无效，阻止非诊断命令。
+
+## 非目标
+
+- 加载时的向后兼容性（遗留键不会自动迁移）。
+- 静默丢弃未识别的键。
+
+## 严格验证规则
+
+- 配置必须在每个层级精确匹配 schema。
+- 未知键是验证错误（根级和嵌套级均不允许透传）。
+- `plugins.entries.<id>.config` 必须由插件的 schema 进行验证。
+  - 如果插件缺少 schema，**拒绝插件加载**并显示明确的错误信息。
+- 未知的 `channels.<id>` 键是错误，除非插件清单声明了该渠道 id。
+- 所有插件都必须提供插件清单（`openclaw.plugin.json`）。
+
+## 插件 schema 强制执行
+
+- 每个插件为其配置提供严格的 JSON Schema（内联在清单中）。
+- 插件加载流程：
+  1. 解析插件清单 + schema（`openclaw.plugin.json`）。
+  2. 根据 schema 验证配置。
+  3. 如果缺少 schema 或配置无效：阻止插件加载，记录错误。
+- 错误信息包括：
+  - 插件 id
+  - 原因（缺少 schema / 配置无效）
+  - 验证失败的路径
+- 已禁用的插件保留其配置，但 Doctor + 日志会显示警告。
+
+## Doctor 流程
+
+- 每次加载配置时都会运行 Doctor（默认 dry-run 模式）。
+- 如果配置无效：
+  - 打印摘要 + 可操作的错误信息。
+  - 提示：`openclaw doctor --fix`。
+- `openclaw doctor --fix`：
+  - 应用迁移。
+  - 移除未知键。
+  - 写入更新后的配置。
+
+## 命令控制（配置无效时）
+
+允许执行（仅限诊断命令）：
+
+- `openclaw doctor`
+- `openclaw logs`
+- `openclaw health`
+- `openclaw help`
+- `openclaw status`
+- `openclaw gateway status`
+
+其他所有命令必须直接失败并提示："Config invalid. Run `openclaw doctor --fix`."
+
+## 错误用户体验格式
+
+- 单个摘要标题。
+- 分组展示：
+  - 未知键（完整路径）
+  - 遗留键 / 需要迁移
+  - 插件加载失败（插件 id + 原因 + 路径）
+
+## 实现涉及的文件
+
+- `src/config/zod-schema.ts`：移除根级 passthrough；所有对象使用 strict 模式。
+- `src/config/zod-schema.providers.ts`：确保渠道 schema 为 strict 模式。
+- `src/config/validation.ts`：遇到未知键时失败；不应用遗留迁移。
+- `src/config/io.ts`：移除遗留自动迁移；始终运行 doctor dry-run。
+- `src/config/legacy*.ts`：将用法迁移到仅限 doctor 使用。
+- `src/plugins/*`：添加 schema 注册表 + 加载控制。
+- `src/cli` 中的 CLI 命令控制。
+
+## 测试
+
+- 未知键拒绝（根级 + 嵌套级）。
+- 插件缺少 schema → 插件加载被阻止并显示明确错误。
+- 配置无效 → Gateway网关启动被阻止，诊断命令除外。
+- Doctor dry-run 自动运行；`doctor --fix` 写入修正后的配置。

package/docs/zh-CN/reference/AGENTS.default.md

@@ -0,0 +1,131 @@
+---
+read_when:
+  - 开始新的 OpenClaw 智能体会话
+  - 启用或审查默认 Skills
+summary: 默认 OpenClaw 智能体指令及个人助手设置的 Skills 清单
+x-i18n:
+  generated_at: "2026-02-01T21:36:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 20ec2b8d8fc03c16bbf0a75f011092e86382ca4182e8c0a4bc5f8ffd2be9c647
+  source_path: reference/AGENTS.default.md
+  workflow: 15
+---
+
+# AGENTS.md — OpenClaw 个人助手（默认）
+
+## 首次运行（推荐）
+
+OpenClaw 为智能体使用专用的工作区目录。默认路径：`~/.openclaw/workspace`（可通过 `agents.defaults.workspace` 配置）。
+
+1. 创建工作区（如果尚不存在）：
+
+```bash
+mkdir -p ~/.openclaw/workspace
+```
+
+2. 将默认工作区模板复制到工作区：
+
+```bash
+cp docs/reference/templates/AGENTS.md ~/.openclaw/workspace/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/TOOLS.md
+```
+
+3. 可选：如果你需要个人助手 Skills 清单，请用此文件替换 AGENTS.md：
+
+```bash
+cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
+```
+
+4. 可选：通过设置 `agents.defaults.workspace` 选择不同的工作区（支持 `~`）：
+
+```json5
+{
+  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
+}
+```
+
+## 安全默认设置
+
+- 不要将目录内容或密钥转储到聊天中。
+- 除非被明确要求，不要执行破坏性命令。
+- 不要向外部消息平台发送部分/流式回复（只发送最终回复）。
+
+## 会话启动（必需）
+
+- 读取 `SOUL.md`、`USER.md`、`memory.md`，以及 `memory/` 中今天和昨天的文件。
+- 在回复之前完成上述操作。
+
+## 灵魂文件（必需）
+
+- `SOUL.md` 定义身份、语气和边界。保持其内容最新。
+- 如果你修改了 `SOUL.md`，请告知用户。
+- 每次会话你都是一个全新实例；连续性存储在这些文件中。
+
+## 共享空间（推荐）
+
+- 你不是用户的代言人；在群聊或公开渠道中请谨慎发言。
+- 不要分享私人数据、联系信息或内部笔记。
+
+## 记忆系统（推荐）
+
+- 每日日志：`memory/YYYY-MM-DD.md`（如需要请创建 `memory/` 目录）。
+- 长期记忆：`memory.md` 用于持久保存事实、偏好和决策。
+- 会话启动时，读取今天 + 昨天的日志以及 `memory.md`（如果存在）。
+- 记录：决策、偏好、约束条件、待处理事项。
+- 除非被明确要求，避免记录密钥。
+
+## 工具与 Skills
+
+- 工具位于 Skills 中；需要时请遵循每个 Skills 的 `SKILL.md`。
+- 将环境相关的备注保存在 `TOOLS.md`（Skills 备注）中。
+
+## 备份提示（推荐）
+
+如果你将此工作区视为 Clawd 的"记忆"，请将其设为 git 仓库（最好是私有的），以便备份 `AGENTS.md` 和记忆文件。
+
+```bash
+cd ~/.openclaw/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# 可选：添加私有远程仓库并推送
+```
+
+## OpenClaw 的功能
+
+- 运行 WhatsApp Gateway网关 + Pi 编程智能体，使助手可以读写聊天、获取上下文，并通过宿主 Mac 运行 Skills。
+- macOS 应用管理权限（屏幕录制、通知、麦克风），并通过其内置二进制文件提供 `openclaw` CLI。
+- 直接聊天默认合并到智能体的 `main` 会话；群组保持隔离，格式为 `agent:<agentId>:<channel>:group:<id>`（房间/频道：`agent:<agentId>:<channel>:channel:<id>`）；心跳机制保持后台任务存活。
+
+## 核心 Skills（在设置 → Skills 中启用）
+
+- **mcporter** — 用于管理外部 Skills 后端的工具服务器运行时/CLI。
+- **Peekaboo** — 支持可选 AI 视觉分析的快速 macOS 截图工具。
+- **camsnap** — 从 RTSP/ONVIF 安防摄像头捕获帧、片段或运动警报。
+- **oracle** — 支持会话回放和浏览器控制的 OpenAI 就绪智能体 CLI。
+- **eightctl** — 从终端控制你的睡眠。
+- **imsg** — 发送、读取、流式传输 iMessage 和短信。
+- **wacli** — WhatsApp CLI：同步、搜索、发送。
+- **discord** — Discord 操作：表情反应、贴纸、投票。使用 `user:<id>` 或 `channel:<id>` 目标（纯数字 ID 有歧义）。
+- **gog** — Google Suite CLI：Gmail、日历、云端硬盘、通讯录。
+- **spotify-player** — 终端 Spotify 客户端，用于搜索/排队/控制播放。
+- **sag** — 具有 mac 风格 say 体验的 ElevenLabs 语音；默认流式输出到扬声器。
+- **Sonos CLI** — 从脚本控制 Sonos 音箱（发现/状态/播放/音量/分组）。
+- **blucli** — 从脚本播放、分组和自动化 BluOS 播放器。
+- **OpenHue CLI** — Philips Hue 灯光控制，用于场景和自动化。
+- **OpenAI Whisper** — 本地语音转文字，用于快速听写和语音邮件转录。
+- **Gemini CLI** — 从终端使用 Google Gemini 模型进行快速问答。
+- **bird** — X/Twitter CLI，无需浏览器即可发推、回复、阅读话题和搜索。
+- **agent-tools** — 用于自动化和辅助脚本的实用工具包。
+
+## 使用说明
+
+- 脚本编写优先使用 `openclaw` CLI；mac 应用负责处理权限。
+- 从 Skills 标签页运行安装；如果二进制文件已存在，安装按钮会自动隐藏。
+- 保持心跳启用，以便助手可以安排提醒、监控收件箱和触发摄像头捕获。
+- Canvas UI 以全屏方式运行并带有原生叠加层。避免将关键控件放置在左上/右上/底部边缘；在布局中添加明确的边距，不要依赖安全区域内边距。
+- 对于浏览器驱动的验证，请使用 `openclaw browser`（tabs/status/screenshot），配合 OpenClaw 管理的 Chrome 配置文件。
+- 对于 DOM 检查，请使用 `openclaw browser eval|query|dom|snapshot`（需要机器输出时使用 `--json`/`--out`）。
+- 对于交互操作，请使用 `openclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`（click/type 需要快照引用；使用 `evaluate` 进行 CSS 选择器操作）。

package/docs/zh-CN/reference/RELEASING.md

@@ -0,0 +1,123 @@
+---
+read_when:
+  - 发布新的 npm 版本时
+  - 发布新的 macOS 应用版本时
+  - 发布前验证元数据时
+summary: npm + macOS 应用的分步发布检查清单
+x-i18n:
+  generated_at: "2026-02-01T21:37:13Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 97c911cf70a0b98838d871cb99826b99f3da63295a744f412e3c05021363a7b5
+  source_path: reference/RELEASING.md
+  workflow: 15
+---
+
+# 发布检查清单（npm + macOS）
+
+从仓库根目录使用 `pnpm`（Node 22+）。在打标签/发布前确保工作区干净。
+
+## 操作员触发
+
+当操作员说"发布"时，立即执行以下预检（除非被阻塞，否则不要多问）：
+
+- 阅读本文档和 `docs/platforms/mac/release.md`。
+- 从 `~/.profile` 加载环境变量，确认 `SPARKLE_PRIVATE_KEY_FILE` + App Store Connect 变量已设置（SPARKLE_PRIVATE_KEY_FILE 应位于 `~/.profile` 中）。
+- 如需要，使用 `~/Library/CloudStorage/Dropbox/Backup/Sparkle` 中的 Sparkle 密钥。
+
+1. **版本与元数据**
+
+- [ ] 更新 `package.json` 版本号（例如 `2026.1.29`）。
+- [ ] 运行 `pnpm plugins:sync` 以同步扩展包版本 + 变更日志。
+- [ ] 更新 CLI/版本字符串：[`src/cli/program.ts`](https://github.com/openclaw/openclaw/blob/main/src/cli/program.ts) 和 [`src/provider-web.ts`](https://github.com/openclaw/openclaw/blob/main/src/provider-web.ts) 中的 Baileys user agent。
+- [ ] 确认包元数据（name、description、repository、keywords、license）以及 `bin` 映射指向 [`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs) 对应 `openclaw`。
+- [ ] 如果依赖有变更，运行 `pnpm install` 确保 `pnpm-lock.yaml` 是最新的。
+
+2. **构建与产物**
+
+- [ ] 如果 A2UI 输入有变更，运行 `pnpm canvas:a2ui:bundle` 并提交更新后的 [`src/canvas-host/a2ui/a2ui.bundle.js`](https://github.com/openclaw/openclaw/blob/main/src/canvas-host/a2ui/a2ui.bundle.js)。
+- [ ] `pnpm run build`（重新生成 `dist/`）。
+- [ ] 验证 npm 包的 `files` 包含所有必需的 `dist/*` 文件夹（特别是 `dist/node-host/**` 和 `dist/acp/**`，用于无界面 node + ACP CLI）。
+- [ ] 确认 `dist/build-info.json` 存在并包含预期的 `commit` 哈希（CLI 横幅在 npm 安装时使用此信息）。
+- [ ] 可选：构建后运行 `npm pack --pack-destination /tmp`；检查 tarball 内容并保留用于 GitHub 发布（**不要**提交它）。
+
+3. **变更日志与文档**
+
+- [ ] 更新 `CHANGELOG.md`，包含面向用户的重点内容（如文件不存在则创建）；条目按版本严格降序排列。
+- [ ] 确保 README 中的示例/参数与当前 CLI 行为一致（特别是新命令或选项）。
+
+4. **验证**
+
+- [ ] `pnpm lint`
+- [ ] `pnpm test`（如需覆盖率输出则使用 `pnpm test:coverage`）
+- [ ] `pnpm run build`（测试后的最终安装完整性检查）
+- [ ] `pnpm release:check`（验证 npm pack 内容）
+- [ ] `OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke`（Docker 安装冒烟测试，快速路径；发布前必须执行）
+  - 如果已知上一个 npm 发布版本有问题，为预安装步骤设置 `OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version>` 或 `OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1`。
+- [ ] （可选）完整安装冒烟测试（增加非 root + CLI 覆盖）：`pnpm test:install:smoke`
+- [ ] （可选）安装端到端测试（Docker，运行 `curl -fsSL https://openclaw.ai/install.sh | bash`，执行新手引导，然后运行真实工具调用）：
+  - `pnpm test:install:e2e:openai`（需要 `OPENAI_API_KEY`）
+  - `pnpm test:install:e2e:anthropic`（需要 `ANTHROPIC_API_KEY`）
+  - `pnpm test:install:e2e`（需要两个密钥；运行两个提供商）
+- [ ] （可选）如果你的更改影响了发送/接收路径，抽查 Web Gateway网关。
+
+5. **macOS 应用（Sparkle）**
+
+- [ ] 构建 + 签名 macOS 应用，然后打包为 zip 用于分发。
+- [ ] 生成 Sparkle appcast（通过 [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) 生成 HTML 说明）并更新 `appcast.xml`。
+- [ ] 保留应用 zip（和可选的 dSYM zip）以附加到 GitHub 发布。
+- [ ] 按照 [macOS 发布](/platforms/mac/release) 获取确切的命令和所需的环境变量。
+  - `APP_BUILD` 必须是数字且单调递增（不含 `-beta`），以便 Sparkle 正确比较版本。
+  - 如果进行公证，使用从 App Store Connect API 环境变量创建的 `openclaw-notary` 钥匙串配置文件（参见 [macOS 发布](/platforms/mac/release)）。
+
+6. **发布（npm）**
+
+- [ ] 确认 git 状态干净；按需提交并推送。
+- [ ] 如需要，`npm login`（验证 2FA）。
+- [ ] `npm publish --access public`（预发布版本使用 `--tag beta`）。
+- [ ] 验证注册表：`npm view openclaw version`、`npm view openclaw dist-tags` 和 `npx -y openclaw@X.Y.Z --version`（或 `--help`）。
+
+### 故障排除（来自 2.0.0-beta2 发布的经验）
+
+- **npm pack/publish 挂起或生成巨大的 tarball**：`dist/OpenClaw.app` 中的 macOS 应用包（和发布 zip）被包含进了包中。通过 `package.json` 的 `files` 白名单发布内容来修复（包含 dist 子目录、docs、skills；排除应用包）。使用 `npm pack --dry-run` 确认 `dist/OpenClaw.app` 未被列出。
+- **npm auth 在 dist-tags 操作时进入 web 循环**：使用传统认证以获取 OTP 提示：
+  - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add openclaw@X.Y.Z latest`
+- **`npx` 验证失败并报 `ECOMPROMISED: Lock compromised`**：使用新缓存重试：
+  - `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y openclaw@X.Y.Z --version`
+- **延迟修复后需要重新指向标签**：强制更新并推送标签，然后确保 GitHub 发布资产仍然匹配：
+  - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
+
+7. **GitHub 发布 + appcast**
+
+- [ ] 打标签并推送：`git tag vX.Y.Z && git push origin vX.Y.Z`（或 `git push --tags`）。
+- [ ] 为 `vX.Y.Z` 创建/更新 GitHub 发布，**标题为 `openclaw X.Y.Z`**（不仅仅是标签）；正文应包含该版本的**完整**变更日志部分（亮点 + 变更 + 修复），内联展示（不使用裸链接），且**正文中不得重复标题**。
+- [ ] 附加产物：`npm pack` tarball（可选）、`OpenClaw-X.Y.Z.zip` 和 `OpenClaw-X.Y.Z.dSYM.zip`（如已生成）。
+- [ ] 提交更新后的 `appcast.xml` 并推送（Sparkle 从 main 分支获取）。
+- [ ] 从一个干净的临时目录（无 `package.json`）运行 `npx -y openclaw@X.Y.Z send --help` 以确认安装/CLI 入口点正常工作。
+- [ ] 发布/分享发布说明。
+
+## 插件发布范围（npm）
+
+我们只发布 `@openclaw/*` 作用域下的**现有 npm 插件**。未上架 npm 的内置插件仅保留为**磁盘目录形式**（仍通过 `extensions/**` 分发）。
+
+确定列表的流程：
+
+1. `npm search @openclaw --json` 并记录包名。
+2. 与 `extensions/*/package.json` 中的名称进行比较。
+3. 只发布**交集部分**（已在 npm 上的）。
+
+当前 npm 插件列表（按需更新）：
+
+- @openclaw/bluebubbles
+- @openclaw/diagnostics-otel
+- @openclaw/discord
+- @openclaw/lobster
+- @openclaw/matrix
+- @openclaw/msteams
+- @openclaw/nextcloud-talk
+- @openclaw/nostr
+- @openclaw/voice-call
+- @openclaw/zalo
+- @openclaw/zalouser
+
+发布说明还必须标注**新的可选内置插件**，这些插件**默认未启用**（例如：`tlon`）。

package/docs/zh-CN/reference/api-usage-costs.md

@@ -0,0 +1,136 @@
+---
+read_when:
+  - 你想了解哪些功能可能调用付费 API
+  - 你需要审核密钥、费用和用量可见性
+  - 你正在解释 /status 或 /usage 的费用报告
+summary: 审核哪些功能会产生费用、使用了哪些密钥以及如何查看用量
+title: API 用量与费用
+x-i18n:
+  generated_at: "2026-02-01T21:37:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 807d0d88801e919a8246517820644db1e6271d165fa376b2e637f05a9121d8b1
+  source_path: reference/api-usage-costs.md
+  workflow: 15
+---
+
+# API 用量与费用
+
+本文档列出了**可能调用 API 密钥的功能**及其费用的显示位置。重点介绍 OpenClaw 中可能产生提供商用量或付费 API 调用的功能。
+
+## 费用显示位置（聊天 + CLI）
+
+**每会话费用快照**
+
+- `/status` 显示当前会话模型、上下文用量和上次响应的 token 数。
+- 如果模型使用 **API 密钥认证**，`/status` 还会显示上次回复的**预估费用**。
+
+**每条消息费用页脚**
+
+- `/usage full` 在每条回复后附加用量页脚，包括**预估费用**（仅限 API 密钥）。
+- `/usage tokens` 仅显示 token 数；OAuth 流程会隐藏美元费用。
+
+**CLI 用量窗口（提供商配额）**
+
+- `openclaw status --usage` 和 `openclaw channels list` 显示提供商**用量窗口**（配额快照，非每条消息的费用）。
+
+详情和示例请参阅 [Token 用量与费用](/token-use)。
+
+## 密钥的发现方式
+
+OpenClaw 可以从以下来源获取凭据：
+
+- **认证配置文件**（按智能体配置，存储在 `auth-profiles.json` 中）。
+- **环境变量**（例如 `OPENAI_API_KEY`、`BRAVE_API_KEY`、`FIRECRAWL_API_KEY`）。
+- **配置文件**（`models.providers.*.apiKey`、`tools.web.search.*`、`tools.web.fetch.firecrawl.*`、`memorySearch.*`、`talk.apiKey`）。
+- **Skills**（`skills.entries.<name>.apiKey`），可能会将密钥导出到 Skills 进程的环境变量中。
+
+## 可能消耗密钥的功能
+
+### 1）核心模型响应（聊天 + 工具）
+
+每次回复或工具调用都使用**当前模型提供商**（OpenAI、Anthropic 等）。这是用量和费用的主要来源。
+
+定价配置请参阅[模型](/providers/models)，显示方式请参阅 [Token 用量与费用](/token-use)。
+
+### 2）媒体理解（音频/图像/视频）
+
+入站媒体可以在回复生成前进行摘要/转录。这会使用模型/提供商 API。
+
+- 音频：OpenAI / Groq / Deepgram（当密钥存在时**自动启用**）。
+- 图像：OpenAI / Anthropic / Google。
+- 视频：Google。
+
+请参阅[媒体理解](/nodes/media-understanding)。
+
+### 3）记忆嵌入 + 语义搜索
+
+语义记忆搜索在配置为远程提供商时使用**嵌入 API**：
+
+- `memorySearch.provider = "openai"` → OpenAI 嵌入
+- `memorySearch.provider = "gemini"` → Gemini 嵌入
+- 本地嵌入失败时可选回退到 OpenAI
+
+你可以使用 `memorySearch.provider = "local"` 保持本地运行（无 API 用量）。
+
+请参阅[记忆](/concepts/memory)。
+
+### 4）网页搜索工具（Brave / 通过 OpenRouter 使用 Perplexity）
+
+`web_search` 使用 API 密钥，可能产生使用费用：
+
+- **Brave Search API**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
+- **Perplexity**（通过 OpenRouter）：`PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY`
+
+**Brave 免费套餐（额度充裕）：**
+
+- **每月 2,000 次请求**
+- **每秒 1 次请求**
+- **需要信用卡**进行验证（除非升级否则不会收费）
+
+请参阅[网页工具](/tools/web)。
+
+### 5）网页抓取工具（Firecrawl）
+
+`web_fetch` 在存在 API 密钥时可以调用 **Firecrawl**：
+
+- `FIRECRAWL_API_KEY` 或 `tools.web.fetch.firecrawl.apiKey`
+
+如果未配置 Firecrawl，该工具会回退到直接抓取 + 可读性提取（无付费 API）。
+
+请参阅[网页工具](/tools/web)。
+
+### 6）提供商用量快照（状态/健康检查）
+
+某些状态命令会调用**提供商用量端点**以显示配额窗口或认证健康状态。这些通常是低频调用，但仍会访问提供商 API：
+
+- `openclaw status --usage`
+- `openclaw models status --json`
+
+请参阅[模型 CLI](/cli/models)。
+
+### 7）压缩保护摘要
+
+压缩保护功能可以使用**当前模型**对会话历史进行摘要，运行时会调用提供商 API。
+
+请参阅[会话管理 + 压缩](/reference/session-management-compaction)。
+
+### 8）模型扫描/探测
+
+`openclaw models scan` 可以探测 OpenRouter 模型，启用探测时会使用 `OPENROUTER_API_KEY`。
+
+请参阅[模型 CLI](/cli/models)。
+
+### 9）语音对话（Talk）
+
+语音对话模式在配置后可以调用 **ElevenLabs**：
+
+- `ELEVENLABS_API_KEY` 或 `talk.apiKey`
+
+请参阅[语音对话模式](/nodes/talk)。
+
+### 10）Skills（第三方 API）
+
+Skills 可以在 `skills.entries.<name>.apiKey` 中存储 `apiKey`。如果 Skills 使用该密钥调用外部 API，则会根据 Skills 的提供商产生费用。
+
+请参阅[Skills](/tools/skills)。

package/docs/zh-CN/reference/device-models.md

@@ -0,0 +1,54 @@
+---
+read_when:
+  - 更新设备型号标识符映射或 NOTICE/许可证文件
+  - 更改实例 UI 中设备名称的显示方式
+summary: OpenClaw 如何内置 Apple 设备型号标识符以在 macOS 应用中显示友好名称。
+title: 设备型号数据库
+x-i18n:
+  generated_at: "2026-02-01T21:37:07Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1d99c2538a0d8fdd80fa468fa402f63479ef2522e83745a0a46527a86238aeb2
+  source_path: reference/device-models.md
+  workflow: 15
+---
+
+# 设备型号数据库（友好名称）
+
+macOS 配套应用通过将 Apple 型号标识符（例如 `iPad16,6`、`Mac16,6`）映射为人类可读的名称，在**实例** UI 中显示友好的 Apple 设备型号名称。
+
+该映射以 JSON 形式内置于：
+
+- `apps/macos/Sources/OpenClaw/Resources/DeviceModels/`
+
+## 数据来源
+
+我们目前内置的映射来自 MIT 许可的仓库：
+
+- `kyle-seongwoo-jun/apple-device-identifiers`
+
+为保持构建的确定性，JSON 文件固定到特定的上游提交（记录在 `apps/macos/Sources/OpenClaw/Resources/DeviceModels/NOTICE.md` 中）。
+
+## 更新数据库
+
+1. 选择要固定的上游提交（iOS 和 macOS 各一个）。
+2. 更新 `apps/macos/Sources/OpenClaw/Resources/DeviceModels/NOTICE.md` 中的提交哈希。
+3. 重新下载固定到这些提交的 JSON 文件：
+
+```bash
+IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
+MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
+  -o apps/macos/Sources/OpenClaw/Resources/DeviceModels/ios-device-identifiers.json
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
+  -o apps/macos/Sources/OpenClaw/Resources/DeviceModels/mac-device-identifiers.json
+```
+
+4. 确保 `apps/macos/Sources/OpenClaw/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` 仍与上游一致（如果上游许可证发生变更，请替换该文件）。
+5. 验证 macOS 应用能够正常构建（无警告）：
+
+```bash
+swift build --package-path apps/macos
+```

package/docs/zh-CN/reference/rpc.md

@@ -0,0 +1,48 @@
+---
+read_when:
+  - 添加或修改外部 CLI 集成
+  - 调试 RPC 适配器（signal-cli、imsg）
+summary: 外部 CLI（signal-cli、imsg）的 RPC 适配器及 Gateway网关模式
+title: RPC 适配器
+x-i18n:
+  generated_at: "2026-02-01T21:37:06Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c04edc952390304a22a3a4763aca00a0311b38d390477ec0be5fe485ec257fa7
+  source_path: reference/rpc.md
+  workflow: 15
+---
+
+# RPC 适配器
+
+OpenClaw 通过 JSON-RPC 集成外部 CLI。目前使用两种模式。
+
+## 模式 A：HTTP 守护进程（signal-cli）
+
+- `signal-cli` 作为守护进程运行，通过 HTTP 提供 JSON-RPC。
+- 事件流使用 SSE（`/api/v1/events`）。
+- 健康探测：`/api/v1/check`。
+- 当 `channels.signal.autoStart=true` 时，OpenClaw 管理其生命周期。
+
+设置和端点详见 [Signal](/channels/signal)。
+
+## 模式 B：stdio 子进程（imsg）
+
+- OpenClaw 将 `imsg rpc` 作为子进程启动。
+- JSON-RPC 通过 stdin/stdout 以行分隔传输（每行一个 JSON 对象）。
+- 无需 TCP 端口，无需守护进程。
+
+使用的核心方法：
+
+- `watch.subscribe` → 通知（`method: "message"`）
+- `watch.unsubscribe`
+- `send`
+- `chats.list`（探测/诊断）
+
+设置和寻址方式（推荐使用 `chat_id`）详见 [iMessage](/channels/imessage)。
+
+## 适配器指南
+
+- Gateway网关管理进程（启动/停止与提供商生命周期绑定）。
+- 保持 RPC 客户端的弹性：超时、退出时重启。
+- 优先使用稳定 ID（例如 `chat_id`）而非显示字符串。