Docs: normalize zh-CN terminology + tone

What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style Tests: pnpm docs:build
2026-06-29 01:02:03 +03:00 · 2026-02-02 15:46:45 +01:00
parent 2b1f68c928
commit 5676a6b38d
237 changed files with 2322 additions and 2337 deletions
@@ -1,8 +1,8 @@
 ---
 read_when:
  - 开始新的 OpenClaw 智能体会话
-  - 启用或审查默认技能
-summary: 默认 OpenClaw 智能体指令及个人助手设置的技能清单
+  - 启用或审查默认 Skills
+summary: 默认 OpenClaw 智能体指令及个人助手设置的 Skills 清单
 x-i18n:
  generated_at: "2026-02-01T21:36:58Z"
  model: claude-opus-4-5
@@ -32,7 +32,7 @@ cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md
 cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/TOOLS.md
 ```

-3. 可选：如果您需要个人助手技能清单，请用此文件替换 AGENTS.md：
+3. 可选：如果你需要个人助手 Skills 清单，请用此文件替换 AGENTS.md：

 ```bash
 cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
@@ -60,12 +60,12 @@ cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
 ## 灵魂文件（必需）

 - `SOUL.md` 定义身份、语气和边界。保持其内容最新。
- 如果您修改了 `SOUL.md`，请告知用户。
- 每次会话您都是一个全新实例；连续性存储在这些文件中。
+- 如果你修改了 `SOUL.md`，请告知用户。
+- 每次会话你都是一个全新实例；连续性存储在这些文件中。

 ## 共享空间（推荐）

- 您不是用户的代言人；在群聊或公开渠道中请谨慎发言。
+- 你不是用户的代言人；在群聊或公开渠道中请谨慎发言。
 - 不要分享私人数据、联系信息或内部笔记。

 ## 记忆系统（推荐）
@@ -76,14 +76,14 @@ cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
 - 记录：决策、偏好、约束条件、待处理事项。
 - 除非被明确要求，避免记录密钥。

-## 工具与技能
+## 工具与 Skills

- 工具位于技能中；需要时请遵循每个技能的 `SKILL.md`。
- 将环境相关的备注保存在 `TOOLS.md`（技能备注）中。
+- 工具位于 Skills 中；需要时请遵循每个 Skills 的 `SKILL.md`。
+- 将环境相关的备注保存在 `TOOLS.md`（Skills 备注）中。

 ## 备份提示（推荐）

-如果您将此工作区视为 Clawd 的"记忆"，请将其设为 git 仓库（最好是私有的），以便备份 `AGENTS.md` 和记忆文件。
+如果你将此工作区视为 Clawd 的"记忆"，请将其设为 git 仓库（最好是私有的），以便备份 `AGENTS.md` 和记忆文件。

 ```bash
 cd ~/.openclaw/workspace
@@ -95,17 +95,17 @@ git commit -m "Add Clawd workspace"

 ## OpenClaw 的功能

- 运行 WhatsApp Gateway + Pi 编程智能体，使助手可以读写聊天、获取上下文，并通过宿主 Mac 运行技能。
+- 运行 WhatsApp Gateway网关 + Pi 编程智能体，使助手可以读写聊天、获取上下文，并通过宿主 Mac 运行 Skills。
 - macOS 应用管理权限（屏幕录制、通知、麦克风），并通过其内置二进制文件提供 `openclaw` CLI。
 - 直接聊天默认合并到智能体的 `main` 会话；群组保持隔离，格式为 `agent:<agentId>:<channel>:group:<id>`（房间/频道：`agent:<agentId>:<channel>:channel:<id>`）；心跳机制保持后台任务存活。

-## 核心技能（在设置 → 技能中启用）
+## 核心 Skills（在设置 → Skills 中启用）

- **mcporter** — 用于管理外部技能后端的工具服务器运行时/CLI。
+- **mcporter** — 用于管理外部 Skills 后端的工具服务器运行时/CLI。
 - **Peekaboo** — 支持可选 AI 视觉分析的快速 macOS 截图工具。
 - **camsnap** — 从 RTSP/ONVIF 安防摄像头捕获帧、片段或运动警报。
 - **oracle** — 支持会话回放和浏览器控制的 OpenAI 就绪智能体 CLI。
- **eightctl** — 从终端控制您的睡眠。
+- **eightctl** — 从终端控制你的睡眠。
 - **imsg** — 发送、读取、流式传输 iMessage 和短信。
 - **wacli** — WhatsApp CLI：同步、搜索、发送。
 - **discord** — Discord 操作：表情反应、贴纸、投票。使用 `user:<id>` 或 `channel:<id>` 目标（纯数字 ID 有歧义）。
@@ -123,7 +123,7 @@ git commit -m "Add Clawd workspace"
 ## 使用说明

 - 脚本编写优先使用 `openclaw` CLI；mac 应用负责处理权限。
- 从技能标签页运行安装；如果二进制文件已存在，安装按钮会自动隐藏。
+- 从 Skills 标签页运行安装；如果二进制文件已存在，安装按钮会自动隐藏。
 - 保持心跳启用，以便助手可以安排提醒、监控收件箱和触发摄像头捕获。
 - Canvas UI 以全屏方式运行并带有原生叠加层。避免将关键控件放置在左上/右上/底部边缘；在布局中添加明确的边距，不要依赖安全区域内边距。
 - 对于浏览器驱动的验证，请使用 `openclaw browser`（tabs/status/screenshot），配合 OpenClaw 管理的 Chrome 配置文件。
@@ -55,11 +55,11 @@ x-i18n:
 - [ ] `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`，执行上手引导，然后运行真实工具调用）：
+- [ ] （可选）安装端到端测试（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。
+- [ ] （可选）如果你的更改影响了发送/接收路径，抽查 Web Gateway网关。

 5. **macOS 应用（Sparkle）**

@@ -1,8 +1,8 @@
 ---
 read_when:
-  - 您想了解哪些功能可能调用付费 API
-  - 您需要审核密钥、费用和用量可见性
-  - 您正在解释 /status 或 /usage 的费用报告
+  - 你想了解哪些功能可能调用付费 API
+  - 你需要审核密钥、费用和用量可见性
+  - 你正在解释 /status 或 /usage 的费用报告
 summary: 审核哪些功能会产生费用、使用了哪些密钥以及如何查看用量
 title: API 用量与费用
 x-i18n:
@@ -43,7 +43,7 @@ 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.entries.<name>.apiKey`），可能会将密钥导出到技能进程的环境变量中。
+- **Skills**（`skills.entries.<name>.apiKey`），可能会将密钥导出到 Skills 进程的环境变量中。

 ## 可能消耗密钥的功能

@@ -71,7 +71,7 @@ OpenClaw 可以从以下来源获取凭据：
 - `memorySearch.provider = "gemini"` → Gemini 嵌入
 - 本地嵌入失败时可选回退到 OpenAI

-您可以使用 `memorySearch.provider = "local"` 保持本地运行（无 API 用量）。
+你可以使用 `memorySearch.provider = "local"` 保持本地运行（无 API 用量）。

 请参阅[记忆](/concepts/memory)。

@@ -129,8 +129,8 @@ OpenClaw 可以从以下来源获取凭据：

 请参阅[语音对话模式](/nodes/talk)。

-### 10）技能（第三方 API）
+### 10）Skills（第三方 API）

-技能可以在 `skills.entries.<name>.apiKey` 中存储 `apiKey`。如果技能使用该密钥调用外部 API，则会根据技能的提供商产生费用。
+Skills 可以在 `skills.entries.<name>.apiKey` 中存储 `apiKey`。如果 Skills 使用该密钥调用外部 API，则会根据 Skills 的提供商产生费用。

-请参阅[技能](/tools/skills)。
+请参阅[Skills](/tools/skills)。
@@ -2,7 +2,7 @@
 read_when:
  - 添加或修改外部 CLI 集成
  - 调试 RPC 适配器（signal-cli、imsg）
-summary: 外部 CLI（signal-cli、imsg）的 RPC 适配器及 Gateway 模式
+summary: 外部 CLI（signal-cli、imsg）的 RPC 适配器及 Gateway网关模式
 title: RPC 适配器
 x-i18n:
  generated_at: "2026-02-01T21:37:06Z"
@@ -43,6 +43,6 @@ OpenClaw 通过 JSON-RPC 集成外部 CLI。目前使用两种模式。

 ## 适配器指南

- Gateway 管理进程（启动/停止与提供商生命周期绑定）。
+- Gateway网关管理进程（启动/停止与提供商生命周期绑定）。
 - 保持 RPC 客户端的弹性：超时、退出时重启。
 - 优先使用稳定 ID（例如 `chat_id`）而非显示字符串。
@@ -1,8 +1,8 @@
 ---
 read_when:
-  - 您需要调试会话 ID、对话记录 JSONL 或 sessions.json 字段
-  - 您正在修改自动压缩行为或添加"压缩前"清理逻辑
-  - 您想要实现记忆刷写或静默系统轮次
+  - 你需要调试会话 ID、对话记录 JSONL 或 sessions.json 字段
+  - 你正在修改自动压缩行为或添加"压缩前"清理逻辑
+  - 你想要实现记忆刷写或静默系统轮次
 summary: 深入解析：会话存储 + 对话记录、生命周期及（自动）压缩内部机制
 title: 会话管理深入解析
 x-i18n:
@@ -26,7 +26,7 @@ x-i18n:
 - **压缩**（手动 + 自动压缩）以及压缩前工作的挂钩位置
 - **静默清理**（例如不应产生用户可见输出的记忆写入）

-如果您想先了解更高层级的概览，请从以下内容开始：
+如果你想先了解更高层级的概览，请从以下内容开始：

 - [/concepts/session](/concepts/session)
 - [/concepts/compaction](/concepts/compaction)
@@ -35,12 +35,12 @@ x-i18n:

 ---

-## 数据源：Gateway
+## 数据源：Gateway网关

-OpenClaw 围绕单个 **Gateway 进程**设计，该进程拥有会话状态。
+OpenClaw 围绕单个 **Gateway网关进程**设计，该进程拥有会话状态。

- UI（macOS 应用、Web 控制界面、TUI）应向 Gateway 查询会话列表和 token 计数。
- 在远程模式下，会话文件位于远程主机上；"检查本地 Mac 文件"不会反映 Gateway 正在使用的内容。
+- UI（macOS 应用、Web 控制界面、TUI）应向 Gateway网关查询会话列表和 token 计数。
+- 在远程模式下，会话文件位于远程主机上；"检查本地 Mac 文件"不会反映 Gateway网关正在使用的内容。

 ---

@@ -62,7 +62,7 @@ OpenClaw 通过两个层持久化会话：

 ## 磁盘位置

-每个智能体，在 Gateway 主机上：
+每个智能体，在 Gateway网关主机上：

 - 存储：`~/.openclaw/agents/<agentId>/sessions/sessions.json`
 - 对话记录：`~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
@@ -74,7 +74,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。

 ## 会话键（`sessionKey`）

-`sessionKey` 标识*您所在的对话桶*（路由 + 隔离）。
+`sessionKey` 标识*你所在的对话桶*（路由 + 隔离）。

 常见模式：

@@ -95,7 +95,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
 经验法则：

 - **重置**（`/new`、`/reset`）为该 `sessionKey` 创建新的 `sessionId`。
- **每日重置**（默认为 Gateway 主机本地时间凌晨 4:00）在重置边界后的下一条消息时创建新的 `sessionId`。
+- **每日重置**（默认为 Gateway网关主机本地时间凌晨 4:00）在重置边界后的下一条消息时创建新的 `sessionId`。
 - **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）在空闲窗口后收到消息时创建新的 `sessionId`。当每日重置和空闲过期同时配置时，先到期的优先。

 实现细节：决策发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()` 函数。
@@ -124,7 +124,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
 - `memoryFlushAt`：上次压缩前记忆刷写的时间戳
 - `memoryFlushCompactionCount`：上次刷写运行时的压缩计数

-存储可安全编辑，但 Gateway 是权威来源：随着会话运行，它可能重写或重新注入条目。
+存储可安全编辑，但 Gateway网关是权威来源：随着会话运行，它可能重写或重新注入条目。

 ---

@@ -145,7 +145,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
 - `compaction`：持久化的压缩摘要，包含 `firstKeptEntryId` 和 `tokensBefore`
 - `branch_summary`：导航树分支时的持久化摘要

-OpenClaw 有意**不**"修复"对话记录；Gateway 使用 `SessionManager` 来读写它们。
+OpenClaw 有意**不**"修复"对话记录；Gateway网关使用 `SessionManager` 来读写它们。

 ---

@@ -156,7 +156,7 @@ OpenClaw 有意**不**"修复"对话记录；Gateway 使用 `SessionManager` 来
 1. **模型上下文窗口**：每个模型的硬上限（模型可见的 token 数）
 2. **会话存储计数器**：写入 `sessions.json` 的滚动统计（用于 /status 和仪表板）

-如果您正在调整限制：
+如果你正在调整限制：

 - 上下文窗口来自模型目录（可通过配置覆盖）。
 - 存储中的 `contextTokens` 是运行时估算/报告值；不要将其视为严格保证。
@@ -226,7 +226,7 @@ OpenClaw 还为嵌入式运行强制执行安全下限：

 ## 用户可见界面

-您可以通过以下方式观察压缩和会话状态：
+你可以通过以下方式观察压缩和会话状态：

 - `/status`（在任何聊天会话中）
 - `openclaw status`（CLI）
@@ -273,16 +273,16 @@ OpenClaw 使用**预阈值刷写**方法：
 - 当会话工作区为只读（`workspaceAccess: "ro"` 或 `"none"`）时跳过刷写。
 - 工作区文件布局和写入模式参阅[记忆](/concepts/memory)。

-Pi 也在扩展 API 中暴露了 `session_before_compact` 钩子，但 OpenClaw 的刷写逻辑目前在 Gateway 侧。
+Pi 也在扩展 API 中暴露了 `session_before_compact` 钩子，但 OpenClaw 的刷写逻辑目前在 Gateway网关侧。

 ---

 ## 故障排除清单

 - 会话键错误？从 [/concepts/session](/concepts/session) 开始，确认 `/status` 中的 `sessionKey`。
- 存储与对话记录不匹配？确认 Gateway 主机以及 `openclaw status` 中的存储路径。
+- 存储与对话记录不匹配？确认 Gateway网关主机以及 `openclaw status` 中的存储路径。
 - 压缩过于频繁？检查：
  - 模型上下文窗口（太小）
  - 压缩设置（`reserveTokens` 相对于模型窗口过高可能导致更早触发压缩）
  - 工具结果膨胀：启用/调整会话修剪
- 静默轮次泄露？确认回复以 `NO_REPLY`（精确 token）开头，且您使用的构建版本包含流式传输抑制修复。
+- 静默轮次泄露？确认回复以 `NO_REPLY`（精确 token）开头，且你使用的构建版本包含流式传输抑制修复。
@@ -54,7 +54,7 @@ x-i18n:
 - **记忆是有限的** — 如果你想记住什么，就写到文件里
 - "心理笔记"无法在会话重启后保留。文件可以。
 - 当有人说"记住这个" → 更新 `memory/YYYY-MM-DD.md` 或相关文件
- 当你学到教训 → 更新 AGENTS.md、TOOLS.md 或相关技能文件
+- 当你学到教训 → 更新 AGENTS.md、TOOLS.md 或相关 Skills 文件
 - 当你犯了错误 → 记录下来，这样未来的你不会重蹈覆辙
 - **文件 > 大脑** 📝

@@ -128,7 +128,7 @@ x-i18n:

 ## 工具

-技能提供你的工具。当你需要某个工具时，查看它的 `SKILL.md`。在 `TOOLS.md` 中保存本地笔记（摄像头名称、SSH 详情、语音偏好等）。
+Skills 提供你的工具。当你需要某个工具时，查看它的 `SKILL.md`。在 `TOOLS.md` 中保存本地笔记（摄像头名称、SSH 详情、语音偏好等）。

 **🎭 语音故事讲述：** 如果你有 `sag`（ElevenLabs TTS），在讲故事、电影摘要和"故事时间"场景中使用语音！比大段文字更引人入胜。用有趣的声音给大家惊喜。

@@ -15,4 +15,4 @@ x-i18n:

 # 保持此文件为空（或仅包含注释）以跳过心跳 API 调用。

-# 当您希望智能体定期检查某些内容时，在下方添加任务。
+# 当你希望智能体定期检查某些内容时，在下方添加任务。
@@ -1,6 +1,6 @@
 ---
 read_when:
-  - 使用开发 Gateway 模板时
+  - 使用开发 Gateway网关模板时
  - 更新默认开发智能体身份时
 summary: 开发智能体灵魂（C-3PO）
 x-i18n:
@@ -13,7 +13,7 @@ x-i18n:

 # TOOLS.md - 本地备注

-技能定义了工具的*工作方式*。此文件用于记录*你的*具体信息——那些你的环境中独有的内容。
+Skills 定义了工具的*工作方式*。此文件用于记录*你的*具体信息——那些你的环境中独有的内容。

 ## 应该放什么

@@ -46,7 +46,7 @@ x-i18n:

 ## 为什么要分开？

-技能是共享的。你的配置是你自己的。将它们分开意味着你可以更新技能而不丢失你的备注，也可以分享技能而不泄露你的基础设施信息。
+Skills 是共享的。你的配置是你自己的。将它们分开意味着你可以更新 Skills 而不丢失你的备注，也可以分享 Skills 而不泄露你的基础设施信息。

 ---

@@ -1,6 +1,6 @@
 ---
 read_when:
-  - 使用开发 Gateway 模板时
+  - 使用开发 Gateway网关模板时
  - 更新默认的开发智能体身份时
 summary: 开发智能体用户资料 (C-3PO)
 x-i18n:
@@ -16,9 +16,9 @@ x-i18n:

 - 完整测试套件（套件、实时测试、Docker）：[测试](/testing)

- `pnpm test:force`：终止任何占用默认控制端口的残留 Gateway 进程，然后使用隔离的 Gateway 端口运行完整的 Vitest 套件，避免服务器测试与正在运行的实例冲突。当之前的 Gateway 运行导致端口 18789 被占用时使用此命令。
+- `pnpm test:force`：终止任何占用默认控制端口的残留 Gateway网关进程，然后使用隔离的 Gateway网关端口运行完整的 Vitest 套件，避免服务器测试与正在运行的实例冲突。当之前的 Gateway网关运行导致端口 18789 被占用时使用此命令。
 - `pnpm test:coverage`：使用 V8 覆盖率运行 Vitest。全局阈值为 70% 的行/分支/函数/语句覆盖率。覆盖率排除了集成度较高的入口文件（CLI 连接、gateway/telegram 桥接、webchat 静态服务器），以保持目标聚焦于可单元测试的逻辑。
- `pnpm test:e2e`：运行 Gateway 端到端冒烟测试（多实例 WS/HTTP/节点配对）。
+- `pnpm test:e2e`：运行 Gateway网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。
 - `pnpm test:live`：运行提供商实时测试（minimax/zai）。需要 API 密钥和 `LIVE=1`（或提供商特定的 `*_LIVE_TEST=1`）才能取消跳过。

 ## 模型延迟基准测试（本地密钥）
@@ -36,9 +36,9 @@ x-i18n:
 - minimax 中位数 1279ms（最小 1114，最大 2431）
 - opus 中位数 2454ms（最小 1224，最大 3170）

-## 上手引导端到端测试（Docker）
+## 新手引导端到端测试（Docker）

-Docker 是可选的；仅在需要容器化上手引导冒烟测试时使用。
+Docker 是可选的；仅在需要容器化新手引导冒烟测试时使用。

 在干净的 Linux 容器中执行完整的冷启动流程：

@@ -46,7 +46,7 @@ Docker 是可选的；仅在需要容器化上手引导冒烟测试时使用。
 scripts/e2e/onboard-docker.sh
 ```

-此脚本通过伪终端驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway 并运行 `openclaw health`。
+此脚本通过伪终端驱动交互式向导，验证配置/工作区/会话文件，然后启动 Gateway网关并运行 `openclaw health`。

 ## QR 导入冒烟测试（Docker）