docs: canonicalize docs paths and align zh navigation (#11428)

* docs(navigation): canonicalize paths and align zh nav * chore(docs): remove stray .DS_Store * docs(scripts): add non-mint docs link audit * docs(nav): fix zh source paths and preserve legacy redirects (#11428) (thanks @sebslight) * chore(docs): satisfy lint for docs link audit script (#11428) (thanks @sebslight)
2026-04-30 19:51:44 +00:00 · 2026-02-07 15:40:35 -05:00
parent cde29fef71
commit 929a3725d3
148 changed files with 607 additions and 687 deletions
--- a/docs/zh-CN/help/debugging.md
+++ b/docs/zh-CN/help/debugging.md
@@ -0,0 +1,160 @@
+---
+read_when:
+  - 你需要检查原始模型输出以查找推理泄漏
+  - 你想在迭代时以监视模式运行 Gateway 网关
+  - 你需要可重复的调试工作流
+summary: 调试工具：监视模式、原始模型流和追踪推理泄漏
+title: 调试
+x-i18n:
+  generated_at: "2026-02-03T07:47:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 504c824bff4790006c8b73600daca66b919e049178e9711e6e65b6254731911a
+  source_path: help/debugging.md
+  workflow: 15
+---
+
+# 调试
+
+本页介绍用于流式输出的调试辅助工具，特别是当提供商将推理混入正常文本时。
+
+## 运行时调试覆盖
+
+在聊天中使用 `/debug` 设置**仅运行时**配置覆盖（内存中，不写入磁盘）。
+`/debug` 默认禁用；通过 `commands.debug: true` 启用。
+当你需要切换不常用的设置而不编辑 `openclaw.json` 时，这非常方便。
+
+示例：
+
+```
+/debug show
+/debug set messages.responsePrefix="[openclaw]"
+/debug unset messages.responsePrefix
+/debug reset
+```
+
+`/debug reset` 清除所有覆盖并返回到磁盘上的配置。
+
+## Gateway 网关监视模式
+
+为了快速迭代，在文件监视器下运行 Gateway 网关：
+
+```bash
+pnpm gateway:watch --force
+```
+
+这映射到：
+
+```bash
+tsx watch src/entry.ts gateway --force
+```
+
+在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们将在每次重启时传递。
+
+## Dev 配置文件 + dev Gateway 网关（--dev）
+
+使用 dev 配置文件来隔离状态，并启动一个安全、可丢弃的调试设置。有**两个** `--dev` 标志：
+
+- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之移动）。
+- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
+
+推荐流程（dev 配置文件 + dev 引导）：
+
+```bash
+pnpm gateway:dev
+OPENCLAW_PROFILE=dev openclaw tui
+```
+
+如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行 CLI。
+
+这会执行：
+
+1. **配置文件隔离**（全局 `--dev`）
+   - `OPENCLAW_PROFILE=dev`
+   - `OPENCLAW_STATE_DIR=~/.openclaw-dev`
+   - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
+   - `OPENCLAW_GATEWAY_PORT=19001`（浏览器/画布相应移动）
+
+2. **Dev 引导**（`gateway --dev`）
+   - 如果缺失则写入最小配置（`gateway.mode=local`，绑定 loopback）。
+   - 将 `agent.workspace` 设置为 dev 工作区。
+   - 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。
+   - 如果缺失则填充工作区文件：
+     `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
+   - 默认身份：**C3‑PO**（礼仪机器人）。
+   - 在 dev 模式下跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
+
+重置流程（全新开始）：
+
+```bash
+pnpm gateway:dev:reset
+```
+
+注意：`--dev` 是**全局**配置文件标志，会被某些运行器吞掉。
+如果你需要明确拼写，请使用环境变量形式：
+
+```bash
+OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
+```
+
+`--reset` 清除配置、凭证、会话和 dev 工作区（使用 `trash`，而非 `rm`），然后重新创建默认的 dev 设置。
+
+提示：如果非 dev Gateway 网关已在运行（launchd/systemd），请先停止它：
+
+```bash
+openclaw gateway stop
+```
+
+## 原始流日志（OpenClaw）
+
+OpenClaw 可以在任何过滤/格式化之前记录**原始助手流**。
+这是查看推理是否作为纯文本增量到达（或作为单独的思考块）的最佳方式。
+
+通过 CLI 启用：
+
+```bash
+pnpm gateway:watch --force --raw-stream
+```
+
+可选路径覆盖：
+
+```bash
+pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
+```
+
+等效环境变量：
+
+```bash
+OPENCLAW_RAW_STREAM=1
+OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
+```
+
+默认文件：
+
+`~/.openclaw/logs/raw-stream.jsonl`
+
+## 原始块日志（pi-mono）
+
+要在解析为块之前捕获**原始 OpenAI 兼容块**，pi-mono 暴露了一个单独的日志记录器：
+
+```bash
+PI_RAW_STREAM=1
+```
+
+可选路径：
+
+```bash
+PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
+```
+
+默认文件：
+
+`~/.pi-mono/logs/raw-openai-completions.jsonl`
+
+> 注意：这仅由使用 pi-mono 的 `openai-completions` 提供商的进程发出。
+
+## 安全注意事项
+
+- 原始流日志可能包含完整提示、工具输出和用户数据。
+- 保持日志在本地并在调试后删除它们。
+- 如果你分享日志，请先清除密钥和个人身份信息。
--- a/docs/zh-CN/help/environment.md
+++ b/docs/zh-CN/help/environment.md
@@ -0,0 +1,88 @@
+---
+read_when:
+  - 你需要知道哪些环境变量被加载，以及加载顺序
+  - 你在调试 Gateway 网关中缺失的 API 密钥
+  - 你在编写提供商认证或部署环境的文档
+summary: OpenClaw 从哪里加载环境变量以及优先级顺序
+title: 环境变量
+x-i18n:
+  generated_at: "2026-02-03T07:47:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b49ae50e5d306612f89f93a86236188a4f2ec23f667e2388b043832be3ac1546
+  source_path: help/environment.md
+  workflow: 15
+---
+
+# 环境变量
+
+OpenClaw 从多个来源拉取环境变量。规则是**永不覆盖现有值**。
+
+## 优先级（从高到低）
+
+1. **进程环境**（Gateway 网关进程从父 shell/守护进程已有的内容）。
+2. **当前工作目录中的 `.env`**（dotenv 默认；不覆盖）。
+3. **全局 `.env`** 位于 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`；不覆盖）。
+4. **配置 `env` 块** 位于 `~/.openclaw/openclaw.json`（仅在缺失时应用）。
+5. **可选的登录 shell 导入**（`env.shellEnv.enabled` 或 `OPENCLAW_LOAD_SHELL_ENV=1`），仅对缺失的预期键名应用。
+
+如果配置文件完全缺失，步骤 4 将被跳过；如果启用了 shell 导入，它仍会运行。
+
+## 配置 `env` 块
+
+两种等效方式设置内联环境变量（都是非覆盖的）：
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-...",
+    },
+  },
+}
+```
+
+## Shell 环境导入
+
+`env.shellEnv` 运行你的登录 shell 并仅导入**缺失的**预期键名：
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000,
+    },
+  },
+}
+```
+
+环境变量等效项：
+
+- `OPENCLAW_LOAD_SHELL_ENV=1`
+- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`
+
+## 配置中的环境变量替换
+
+你可以使用 `${VAR_NAME}` 语法在配置字符串值中直接引用环境变量：
+
+```json5
+{
+  models: {
+    providers: {
+      "vercel-gateway": {
+        apiKey: "${VERCEL_GATEWAY_API_KEY}",
+      },
+    },
+  },
+}
+```
+
+完整详情参见[配置：环境变量替换](/gateway/configuration#env-var-substitution-in-config)。
+
+## 相关内容
+
+- [Gateway 网关配置](/gateway/configuration)
+- [常见问题：环境变量和 .env 加载](/help/faq#env-vars-and-env-loading)
+- [模型概述](/concepts/models)
--- a/docs/zh-CN/help/faq.md
+++ b/docs/zh-CN/help/faq.md
@@ -669,7 +669,7 @@ claude setup-token

 ### 支持 AWS Bedrock 吗

-是的——通过 pi-ai 的 **Amazon Bedrock (Converse)** 提供商进行**手动配置**。你必须在 Gateway 网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参阅 [Amazon Bedrock](/bedrock) 和[模型提供商](/providers/models)。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是有效选项。
+是的——通过 pi-ai 的 **Amazon Bedrock (Converse)** 提供商进行**手动配置**。你必须在 Gateway 网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参阅 [Amazon Bedrock](/providers/bedrock) 和[模型提供商](/providers/models)。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是有效选项。

 ### Codex 认证如何工作

@@ -1094,7 +1094,7 @@ openclaw browser extension path

 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/频道会话（非主键）在 Docker 中运行，而主私信会话保持在主机上。然后通过 `tools.sandbox.tools` 限制沙箱会话中可用的工具。

-设置指南 + 示例配置：[群组：个人私信 + 公开群组](/concepts/groups#pattern-personal-dms-public-groups-single-agent)
+设置指南 + 示例配置：[群组：个人私信 + 公开群组](/channels/groups#pattern-personal-dms-public-groups-single-agent)

 关键配置参考：[Gateway 网关配置](/gateway/configuration#agentsdefaultssandbox)

@@ -1321,7 +1321,7 @@ Gateway 网关监视配置文件并支持热重载：
 - **子智能体：** 需要并行处理时从主智能体生成后台工作。
 - **TUI：** 连接到 Gateway 网关并切换智能体/会话。

-文档：[节点](/nodes)、[远程访问](/gateway/remote)、[多智能体路由](/concepts/multi-agent)、[子智能体](/tools/subagents)、[TUI](/tui)。
+文档：[节点](/nodes)、[远程访问](/gateway/remote)、[多智能体路由](/concepts/multi-agent)、[子智能体](/tools/subagents)、[TUI](/web/tui)。

 ### OpenClaw 浏览器可以无头运行吗

@@ -1527,7 +1527,7 @@ OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量，
 }
 ```

-参阅 [/environment](/environment) 了解优先级和来源详情。
+参阅 [/environment](/help/environment) 了解优先级和来源详情。

 ### 我通过服务启动了 Gateway 网关，但环境变量消失了，怎么办

@@ -1570,7 +1570,7 @@ openclaw models status
 ```

 Copilot 令牌从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。
-参阅 [/concepts/model-providers](/concepts/model-providers) 和 [/environment](/environment)。
+参阅 [/concepts/model-providers](/concepts/model-providers) 和 [/environment](/help/environment)。

 ## 会话与多聊天

@@ -1731,11 +1731,11 @@ openclaw directory groups list --channel whatsapp
 - 提及限制已开启（默认）。你必须 @提及机器人（或匹配 `mentionPatterns`）。
 - 你配置了 `channels.whatsapp.groups` 但没有 `"*"` 且该群组未加入允许列表。

-参阅[群组](/concepts/groups)和[群组消息](/concepts/group-messages)。
+参阅[群组](/channels/groups)和[群组消息](/channels/group-messages)。

 ### 群组/线程与私聊共享上下文吗

-直接聊天默认折叠到主会话。群组/频道有自己的会话键，Telegram 话题 / Discord 线程是独立的会话。参阅[群组](/concepts/groups)和[群组消息](/concepts/group-messages)。
+直接聊天默认折叠到主会话。群组/频道有自己的会话键，Telegram 话题 / Discord 线程是独立的会话。参阅[群组](/channels/groups)和[群组消息](/channels/group-messages)。

 ### 可以创建多少个工作区和智能体

@@ -2410,7 +2410,7 @@ openclaw logs --follow

 在 TUI 中，使用 `/status` 查看当前状态。如果你期望在聊天渠道中收到回复，确保投递已启用（`/deliver on`）。

-文档：[TUI](/tui)、[斜杠命令](/tools/slash-commands)。
+文档：[TUI](/web/tui)、[斜杠命令](/tools/slash-commands)。

 ### 如何完全停止然后启动 Gateway 网关如果你安装了服务：

@@ -2492,7 +2492,7 @@ openclaw message send --target +15555550123 --message "Here you go" --media /pat

 从小处开始。只授予你实际需要的工具和账户的访问权限，以后需要时再扩展。

-文档：[安全](/gateway/security)、[配对](/start/pairing)。
+文档：[安全](/gateway/security)、[配对](/channels/pairing)。

 ### 我能让它自主管理我的短信吗？这安全吗

--- a/docs/zh-CN/help/scripts.md
+++ b/docs/zh-CN/help/scripts.md
@@ -0,0 +1,35 @@
+---
+read_when:
+  - 从仓库运行脚本时
+  - 在 ./scripts 下添加或修改脚本时
+summary: 仓库脚本：用途、范围和安全注意事项
+title: 脚本
+x-i18n:
+  generated_at: "2026-02-01T21:38:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bfedc3c123c4a43b351f793e2137568786f90732723da5fd223c2a088bc59e43
+  source_path: help/scripts.md
+  workflow: 15
+---
+
+# 脚本
+
+`scripts/` 目录包含用于本地工作流和运维任务的辅助脚本。
+当任务明确与某个脚本相关时使用这些脚本；否则优先使用 CLI。
+
+## 约定
+
+- 除非在文档或发布检查清单中引用，否则脚本为**可选**。
+- 当 CLI 接口存在时优先使用（例如：认证监控使用 `openclaw models status --check`）。
+- 假定脚本与特定主机相关；在新机器上运行前请先阅读脚本内容。
+
+## 认证监控脚本
+
+认证监控脚本的文档请参阅：
+[/automation/auth-monitoring](/automation/auth-monitoring)
+
+## 添加脚本时
+
+- 保持脚本专注且有文档说明。
+- 在相关文档中添加简短条目（如果缺少则创建一个）。
--- a/docs/zh-CN/help/submitting-a-pr.md
+++ b/docs/zh-CN/help/submitting-a-pr.md
@@ -0,0 +1,8 @@
+---
+summary: 如何提交高信号 PR
+title: 提交 PR
+---
+
+# 提交 PR
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Submitting a PR](/help/submitting-a-pr)。
--- a/docs/zh-CN/help/submitting-an-issue.md
+++ b/docs/zh-CN/help/submitting-an-issue.md
@@ -0,0 +1,8 @@
+---
+summary: 如何提交高信号 Issue
+title: 提交 Issue
+---
+
+# 提交 Issue
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Submitting an Issue](/help/submitting-an-issue)。
--- a/docs/zh-CN/help/testing.md
+++ b/docs/zh-CN/help/testing.md
@@ -0,0 +1,375 @@
+---
+read_when:
+  - 在本地或 CI 中运行测试
+  - 为模型/提供商问题添加回归测试
+  - 调试 Gateway 网关 + 智能体行为
+summary: 测试套件：单元/端到端/实时测试套件、Docker 运行器，以及每个测试的覆盖范围
+title: 测试
+x-i18n:
+  generated_at: "2026-02-03T09:23:12Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8c236673838731c49464622ac54bf0336acf787b857677c8c2d2aa52949c8ad5
+  source_path: help/testing.md
+  workflow: 15
+---
+
+# 测试
+
+OpenClaw 包含三个 Vitest 测试套件（单元/集成、端到端、实时）以及一小组 Docker 运行器。
+
+本文档是一份"我们如何测试"的指南：
+
+- 每个套件覆盖什么（以及它刻意*不*覆盖什么）
+- 常见工作流程应运行哪些命令（本地、推送前、调试）
+- 实时测试如何发现凭证并选择模型/提供商
+- 如何为现实中的模型/提供商问题添加回归测试
+
+## 快速开始
+
+日常使用：
+
+- 完整检查（推送前的预期流程）：`pnpm build && pnpm check && pnpm test`
+
+当你修改测试或需要额外的信心时：
+
+- 覆盖率检查：`pnpm test:coverage`
+- 端到端套件：`pnpm test:e2e`
+
+调试真实提供商/模型时（需要真实凭证）：
+
+- 实时套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live`
+
+提示：当你只需要一个失败用例时，建议使用下文描述的允许列表环境变量来缩小实时测试范围。
+
+## 测试套件（在哪里运行什么）
+
+可以将这些套件理解为"逐渐增强的真实性"（以及逐渐增加的不稳定性/成本）：
+
+### 单元/集成测试（默认）
+
+- 命令：`pnpm test`
+- 配置：`vitest.config.ts`
+- 文件：`src/**/*.test.ts`
+- 范围：
+  - 纯单元测试
+  - 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置）
+  - 已知问题的确定性回归测试
+- 预期：
+  - 在 CI 中运行
+  - 不需要真实密钥
+  - 应该快速且稳定
+
+### 端到端测试（Gateway 网关冒烟测试）
+
+- 命令：`pnpm test:e2e`
+- 配置：`vitest.e2e.config.ts`
+- 文件：`src/**/*.e2e.test.ts`
+- 范围：
+  - 多实例 Gateway 网关端到端行为
+  - WebSocket/HTTP 接口、节点配对和较重的网络操作
+- 预期：
+  - 在 CI 中运行（当在流水线中启用时）
+  - 不需要真实密钥
+  - 比单元测试有更多活动部件（可能较慢）
+
+### 实时测试（真实提供商 + 真实模型）
+
+- 命令：`pnpm test:live`
+- 配置：`vitest.live.config.ts`
+- 文件：`src/**/*.live.test.ts`
+- 默认：通过 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`）
+- 范围：
+  - "这个提供商/模型用真实凭证*今天*实际能工作吗？"
+  - 捕获提供商格式变更、工具调用怪癖、认证问题和速率限制行为
+- 预期：
+  - 设计上不适合 CI 稳定运行（真实网络、真实提供商策略、配额、故障）
+  - 花费金钱/使用速率限制
+  - 建议运行缩小范围的子集而非"全部"
+  - 实时运行会加载 `~/.profile` 以获取缺失的 API 密钥
+  - Anthropic 密钥轮换：设置 `OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..."`（或 `OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...`）或多个 `ANTHROPIC_API_KEY*` 变量；测试会在遇到速率限制时重试
+
+## 我应该运行哪个套件？
+
+使用这个决策表：
+
+- 编辑逻辑/测试：运行 `pnpm test`（如果改动较大，加上 `pnpm test:coverage`）
+- 涉及 Gateway 网关网络/WS 协议/配对：加上 `pnpm test:e2e`
+- 调试"我的机器人挂了"/提供商特定故障/工具调用：运行缩小范围的 `pnpm test:live`
+
+## 实时测试：模型冒烟测试（配置文件密钥）
+
+实时测试分为两层，以便隔离故障：
+
+- "直接模型"告诉我们提供商/模型是否能用给定的密钥正常响应。
+- "Gateway 网关冒烟测试"告诉我们完整的 Gateway 网关 + 智能体管道是否对该模型正常工作（会话、历史记录、工具、沙箱策略等）。
+
+### 第一层：直接模型补全（无 Gateway 网关）
+
+- 测试：`src/agents/models.profiles.live.test.ts`
+- 目标：
+  - 枚举发现的模型
+  - 使用 `getApiKeyForModel` 选择你有凭证的模型
+  - 每个模型运行一个小型补全（以及需要时的针对性回归测试）
+- 如何启用：
+  - `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
+- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，modern 的别名）以实际运行此套件；否则会跳过以保持 `pnpm test:live` 专注于 Gateway 网关冒烟测试
+- 如何选择模型：
+  - `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.1、Grok 4）
+  - `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
+  - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..."`（逗号分隔的允许列表）
+- 如何选择提供商：
+  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许列表）
+- 密钥来源：
+  - 默认：配置文件存储和环境变量回退
+  - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制**仅使用配置文件存储**
+- 为什么存在这个测试：
+  - 将"提供商 API 损坏/密钥无效"与"Gateway 网关智能体管道损坏"分离
+  - 包含小型、隔离的回归测试（例如：OpenAI Responses/Codex Responses 推理重放 + 工具调用流程）
+
+### 第二层：Gateway 网关 + 开发智能体冒烟测试（"@openclaw"实际做的事）
+
+- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
+- 目标：
+  - 启动一个进程内 Gateway 网关
+  - 创建/修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
+  - 遍历有密钥的模型并断言：
+    - "有意义的"响应（无工具）
+    - 真实的工具调用工作正常（读取探测）
+    - 可选的额外工具探测（执行+读取探测）
+    - OpenAI 回归路径（仅工具调用 → 后续）保持工作
+- 探测详情（以便你能快速解释故障）：
+  - `read` 探测：测试在工作区写入一个随机数文件，要求智能体 `read` 它并回显随机数。
+  - `exec+read` 探测：测试要求智能体 `exec` 将随机数写入临时文件，然后 `read` 回来。
+  - 图像探测：测试附加一个生成的 PNG（猫 + 随机代码），期望模型返回 `cat <CODE>`。
+  - 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
+- 如何启用：
+  - `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
+- 如何选择模型：
+  - 默认：现代允许列表（Opus/Sonnet/Haiku 4.5、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.1、Grok 4）
+  - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
+  - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号分隔列表）来缩小范围
+- 如何选择提供商（避免"OpenRouter 全部"）：
+  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的允许列表）
+- 工具 + 图像探测在此实时测试中始终开启：
+  - `read` 探测 + `exec+read` 探测（工具压力测试）
+  - 当模型声明支持图像输入时运行图像探测
+  - 流程（高层次）：
+    - 测试生成一个带有"CAT"+ 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
+    - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
+    - Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
+    - 嵌入式智能体将多模态用户消息转发给模型
+    - 断言：回复包含 `cat` + 代码（OCR 容差：允许轻微错误）
+
+提示：要查看你的机器上可以测试什么（以及确切的 `provider/model` ID），运行：
+
+```bash
+openclaw models list
+openclaw models list --json
+```
+
+## 实时测试：Anthropic 设置令牌冒烟测试
+
+- 测试：`src/agents/anthropic.setup-token.live.test.ts`
+- 目标：验证 Claude Code CLI 设置令牌（或粘贴的设置令牌配置文件）能完成 Anthropic 提示。
+- 启用：
+  - `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
+  - `OPENCLAW_LIVE_SETUP_TOKEN=1`
+- 令牌来源（选择一个）：
+  - 配置文件：`OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test`
+  - 原始令牌：`OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...`
+- 模型覆盖（可选）：
+  - `OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5`
+
+设置示例：
+
+```bash
+openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
+OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts
+```
+
+## 实时测试：CLI 后端冒烟测试（Claude Code CLI 或其他本地 CLI）
+
+- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
+- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体管道，而不影响你的默认配置。
+- 启用：
+  - `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
+  - `OPENCLAW_LIVE_CLI_BACKEND=1`
+- 默认值：
+  - 模型：`claude-cli/claude-sonnet-4-5`
+  - 命令：`claude`
+  - 参数：`["-p","--output-format","json","--dangerously-skip-permissions"]`
+- 覆盖（可选）：
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'`
+  - `OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'`
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径注入到提示中）。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图像文件路径作为 CLI 参数传递而非提示注入。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）控制设置 `IMAGE_ARG` 时如何传递图像参数。
+  - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。
+- `OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0` 保持 Claude Code CLI MCP 配置启用（默认使用临时空文件禁用 MCP 配置）。
+
+示例：
+
+```bash
+OPENCLAW_LIVE_CLI_BACKEND=1 \
+  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
+  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
+```
+
+### 推荐的实时测试配方
+
+缩小范围的显式允许列表最快且最不易出错：
+
+- 单个模型，直接测试（无 Gateway 网关）：
+  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts`
+
+- 单个模型，Gateway 网关冒烟测试：
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+- 跨多个提供商的工具调用：
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+- Google 专项（Gemini API 密钥 + Antigravity）：
+  - Gemini（API 密钥）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+注意：
+
+- `google/...` 使用 Gemini API（API 密钥）。
+- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
+- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立的认证 + 工具怪癖）。
+- Gemini API 与 Gemini CLI：
+  - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥/配置文件认证）；这是大多数用户说的"Gemini"。
+  - CLI：OpenClaw 调用本地 `gemini` 二进制文件；它有自己的认证，行为可能不同（流式传输/工具支持/版本差异）。
+
+## 实时测试：模型矩阵（我们覆盖什么）
+
+没有固定的"CI 模型列表"（实时测试是可选的），但这些是建议在有密钥的开发机器上定期覆盖的**推荐**模型。
+
+### 现代冒烟测试集（工具调用 + 图像）
+
+这是我们期望保持工作的"常用模型"运行：
+
+- OpenAI（非 Codex）：`openai/gpt-5.2`（可选：`openai/gpt-5.1`）
+- OpenAI Codex：`openai-codex/gpt-5.2`（可选：`openai-codex/gpt-5.2-codex`）
+- Anthropic：`anthropic/claude-opus-4-5`（或 `anthropic/claude-sonnet-4-5`）
+- Google（Gemini API）：`google/gemini-3-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
+- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
+- Z.AI（GLM）：`zai/glm-4.7`
+- MiniMax：`minimax/minimax-m2.1`
+
+运行带工具 + 图像的 Gateway 网关冒烟测试：
+`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+
+### 基线：工具调用（Read + 可选 Exec）
+
+每个提供商系列至少选择一个：
+
+- OpenAI：`openai/gpt-5.2`（或 `openai/gpt-5-mini`）
+- Anthropic：`anthropic/claude-opus-4-5`（或 `anthropic/claude-sonnet-4-5`）
+- Google：`google/gemini-3-flash-preview`（或 `google/gemini-3-pro-preview`）
+- Z.AI（GLM）：`zai/glm-4.7`
+- MiniMax：`minimax/minimax-m2.1`
+
+可选的额外覆盖（锦上添花）：
+
+- xAI：`xai/grok-4`（或最新可用版本）
+- Mistral：`mistral/`…（选择一个你已启用的"工具"能力模型）
+- Cerebras：`cerebras/`…（如果你有访问权限）
+- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
+
+### 视觉：图像发送（附件 → 多模态消息）
+
+在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 视觉能力变体等）以测试图像探测。
+
+### 聚合器/替代 Gateway 网关
+
+如果你启用了密钥，我们也支持通过以下方式测试：
+
+- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具+图像的候选模型）
+- OpenCode Zen：`opencode/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
+
+如果你有凭证/配置，可以在实时矩阵中包含更多提供商：
+
+- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
+- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等）
+
+提示：不要试图在文档中硬编码"所有模型"。权威列表是你机器上 `discoverModels(...)` 返回的内容 + 可用的密钥。
+
+## 凭证（绝不提交）
+
+实时测试以与 CLI 相同的方式发现凭证。实际含义：
+
+- 如果 CLI 能工作，实时测试应该能找到相同的密钥。
+- 如果实时测试说"无凭证"，用调试 `openclaw models list`/模型选择相同的方式调试。
+
+- 配置文件存储：`~/.openclaw/credentials/`（首选；测试中"配置文件密钥"的含义）
+- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
+
+如果你想依赖环境变量密钥（例如在 `~/.profile` 中导出的），在 `source ~/.profile` 后运行本地测试，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
+
+## Deepgram 实时测试（音频转录）
+
+- 测试：`src/media-understanding/providers/deepgram/audio.live.test.ts`
+- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
+
+## Docker 运行器（可选的"在 Linux 中工作"检查）
+
+这些在仓库 Docker 镜像内运行 `pnpm test:live`，挂载你的本地配置目录和工作区（如果挂载了 `~/.profile` 则会加载它）：
+
+- 直接模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`）
+- Gateway 网关 + 开发智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`）
+- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
+- Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
+- 插件（自定义扩展加载 + 注册表冒烟测试）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
+
+有用的环境变量：
+
+- `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw`
+- `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace`
+- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile` 并在运行测试前加载
+- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于缩小运行范围
+- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 确保凭证来自配置文件存储（而非环境变量）
+
+## 文档完整性检查
+
+文档编辑后运行文档检查：`pnpm docs:list`。
+
+## 离线回归测试（CI 安全）
+
+这些是没有真实提供商的"真实管道"回归测试：
+
+- Gateway 网关工具调用（模拟 OpenAI，真实 Gateway 网关 + 智能体循环）：`src/gateway/gateway.tool-calling.mock-openai.test.ts`
+- Gateway 网关向导（WS `wizard.start`/`wizard.next`，写入配置 + 强制认证）：`src/gateway/gateway.wizard.e2e.test.ts`
+
+## 智能体可靠性评估（Skills）
+
+我们已经有一些 CI 安全的测试，它们的行为类似于"智能体可靠性评估"：
+
+- 通过真实 Gateway 网关 + 智能体循环的模拟工具调用（`src/gateway/gateway.tool-calling.mock-openai.test.ts`）。
+- 验证会话连接和配置效果的端到端向导流程（`src/gateway/gateway.wizard.e2e.test.ts`）。
+
+对于 Skills 仍然缺少的内容（参见 [Skills](/tools/skills)）：
+
+- **决策：** 当 Skills 在提示中列出时，智能体是否选择正确的 skill（或避免不相关的）？
+- **合规性：** 智能体是否在使用前读取 `SKILL.md` 并遵循所需的步骤/参数？
+- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。
+
+未来的评估应该首先保持确定性：
+
+- 使用模拟提供商来断言工具调用 + 顺序、skill 文件读取和会话连接的场景运行器。
+- 一小套专注于 skill 的场景（使用 vs 避免、门控、提示注入）。
+- 可选的实时评估（可选的，环境变量门控），仅在 CI 安全套件就位后。
+
+## 添加回归测试（指导）
+
+当你修复在实时测试中发现的提供商/模型问题时：
+
+- 如果可能，添加 CI 安全的回归测试（模拟/存根提供商，或捕获确切的请求形状转换）
+- 如果它本质上是仅限实时的（速率限制、认证策略），保持实时测试范围小且通过环境变量可选
+- 优先针对能捕获问题的最小层：
+  - 提供商请求转换/重放问题 → 直接模型测试
+  - Gateway 网关会话/历史/工具管道问题 → Gateway 网关实时冒烟测试或 CI 安全的 Gateway 网关模拟测试