chore(i18n): refresh zh-CN translations

2026-05-04 11:10:29 +00:00 · 2026-05-04 11:10:29 +00:00 · 8a911eafe4
commit 8a911eafe4
parent 5f20b95dde
3 changed files with 270 additions and 260 deletions
--- a/docs/zh-CN/cli/proxy.md
+++ b/docs/zh-CN/cli/proxy.md
@ -1,15 +1,15 @@
 ---
 read_when:
-    - 你需要在部署前验证由操作员管理的代理路由
+    - 你需要在部署前验证由运维人员管理的代理路由
    - 你需要在本地捕获 OpenClaw 传输流量以进行调试
-    - 你想检查调试代理会话、二进制对象或内置查询预设
+    - 你想检查调试代理会话、二进制大对象或内置查询预设
 summary: '`openclaw proxy` 的 CLI 参考，包括操作员管理的代理验证和本地调试代理捕获检查器'
 title: 代理
 x-i18n:
-    generated_at: "2026-05-04T03:58:59Z"
+    generated_at: "2026-05-04T11:08:55Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
+    source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5
    source_path: cli/proxy.md
    workflow: 16
 ---
@ -18,14 +18,14 @@ x-i18n:

 验证由操作员管理的代理路由，或运行本地显式调试代理并检查捕获的流量。

-在启用 OpenClaw 代理路由之前，使用 `validate` 预先检查由操作员管理的转发代理。其他命令是用于传输层调查的调试工具：它们可以启动本地代理、在启用捕获的情况下运行子命令、列出捕获会话、查询常见流量模式、读取捕获的 blob，以及清除本地捕获数据。
+使用 `validate` 在启用 OpenClaw 代理路由之前预检由操作员管理的转发代理。其他命令是用于传输层调查的调试工具：它们可以启动本地代理、在启用捕获的情况下运行子命令、列出捕获会话、查询常见流量模式、读取捕获的 Blob，以及清除本地捕获数据。

 ## 命令

 ```bash
 openclaw proxy start [--host <host>] [--port <port>]
 openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
-openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
+openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
 openclaw proxy coverage
 openclaw proxy sessions [--limit <count>]
 openclaw proxy query --preset <name> [--session <id>]
@ -35,17 +35,19 @@ openclaw proxy purge

 ## 验证

-`openclaw proxy validate` 会从 `--proxy-url`、配置或 `OPENCLAW_PROXY_URL` 检查有效的由操作员管理的代理 URL。当没有启用并配置代理时，它会报告配置问题；在更改配置之前，使用 `--proxy-url` 进行一次性预检。默认情况下，它会验证公共目标是否能通过代理成功访问，并验证代理无法访问临时回环探针。自定义拒绝目标采用失败即关闭策略：HTTP 响应和不明确的传输失败都会导致失败，除非你可以单独验证特定部署的拒绝信号。
+`openclaw proxy validate` 会检查来自 `--proxy-url`、配置或 `OPENCLAW_PROXY_URL` 的有效由操作员管理的代理 URL。当未启用并配置代理时，它会报告配置问题；在更改配置之前，可使用 `--proxy-url` 进行一次性预检。默认情况下，它会验证公共目标可通过代理成功访问，并验证代理无法访问临时回环探针。自定义拒绝目标采用失败关闭策略：HTTP 响应和含糊的传输失败都会失败，除非你可以单独验证特定部署的拒绝信号。添加 `--apns-reachable` 还会通过代理打开 APNs HTTP/2 CONNECT 隧道，并确认沙箱 APNs 有响应；该探测会使用有意无效的提供商令牌，因此 APNs `403 InvalidProviderToken` 响应就是成功的可达性信号。

 选项：

 - `--json`：打印机器可读的 JSON。
 - `--proxy-url <url>`：验证此代理 URL，而不是配置或环境变量。
- `--allowed-url <url>`：添加一个预期能通过代理成功访问的目标。重复使用可检查多个目标。
- `--denied-url <url>`：添加一个预期会被代理阻止的目标。重复使用可检查多个目标。
+- `--allowed-url <url>`：添加一个预期可通过代理成功访问的目标。可重复使用以检查多个目标。
+- `--denied-url <url>`：添加一个预期会被代理阻止的目标。可重复使用以检查多个目标。
+- `--apns-reachable`：同时验证沙箱 APNs HTTP/2 可通过代理访问。
+- `--apns-authority <url>`：与 `--apns-reachable` 一起探测的 APNs authority（默认为 `https://api.sandbox.push.apple.com`；生产环境为 `https://api.push.apple.com`）。
 - `--timeout-ms <ms>`：每个请求的超时时间，单位为毫秒。

-查看 [网络代理](/zh-CN/security/network-proxy)，了解部署指导和拒绝语义。
+有关部署指导和拒绝语义，请参阅 [网络代理](/zh-CN/security/network-proxy)。

 ## 查询预设

@ -58,16 +60,16 @@ openclaw proxy purge
 - `missing-ack`
 - `error-bursts`

-## 说明
+## 备注

 - `start` 默认使用 `127.0.0.1`，除非设置了 `--host`。
- `run` 会启动本地调试代理，然后运行 `--` 之后的命令。
- 调试代理的直接上游转发会打开上游套接字以用于诊断。当 OpenClaw 托管代理模式处于活动状态时，默认会禁用代理请求和 CONNECT 隧道的直接转发；仅在获准的本地诊断中设置 `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1`。
+- `run` 会启动本地调试代理，然后运行 `--` 后面的命令。
+- 调试代理的直接上游转发会打开上游套接字用于诊断。当 OpenClaw 托管代理模式处于活动状态时，默认禁用代理请求和 CONNECT 隧道的直接转发；仅在获批的本地诊断中设置 `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1`。
 - 当代理配置或目标检查失败时，`validate` 会以代码 1 退出。
 - 捕获内容是本地调试数据；完成后请使用 `openclaw proxy purge`。

-## 相关内容
+## 相关

 - [CLI 参考](/zh-CN/cli)
 - [网络代理](/zh-CN/security/network-proxy)
- [可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)
+- [受信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)
--- a/docs/zh-CN/help/testing-live.md
+++ b/docs/zh-CN/help/testing-live.md
@ -1,35 +1,32 @@
 ---
 read_when:
-    - 运行实时模型矩阵 / CLI 后端 / ACP / 媒体提供商冒烟测试
+    - 运行实时模型矩阵 / CLI 后端 / ACP / media-provider 冒烟测试
    - 调试实时测试凭证解析
-    - 添加新的提供商专用真实环境测试
+    - 添加新的提供商专属实时测试
 sidebarTitle: Live tests
-summary: 实网（涉及网络访问）测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
-title: 测试：实时套件
+summary: 真实环境（涉及网络访问的）测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
+title: 测试：真实环境测试套件
 x-i18n:
-    generated_at: "2026-05-03T04:51:08Z"
+    generated_at: "2026-05-04T11:08:59Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
+    source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016
    source_path: help/testing-live.md
    workflow: 16
 ---

-如需快速开始、QA 运行器、单元/集成套件和 Docker 流程，请参阅
-[测试](/zh-CN/help/testing)。本页涵盖 **live**（会触达网络的）测试
-套件：模型矩阵、CLI 后端、ACP、媒体提供商 live 测试，以及
-凭证处理。
+有关快速开始、QA 运行器、单元/集成套件和 Docker 流程，请参阅
+[测试](/zh-CN/help/testing)。本页涵盖 **实时**（会触达网络）的测试套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及凭证处理。

-## Live：本地配置档冒烟测试命令
+## 实时：本地配置文件冒烟测试命令

-在临时 live 检查前 source `~/.profile`，以便提供商密钥和本地工具
-路径与你的 shell 匹配：
+在临时实时检查前先加载 `~/.profile`，这样提供商密钥和本地工具路径会与你的 shell 匹配：

 ```bash
 source ~/.profile
 ```

-安全媒体冒烟测试：
+安全的媒体冒烟测试：

 ```bash
 pnpm openclaw infer tts convert --local --json \
@ -37,104 +34,102 @@ pnpm openclaw infer tts convert --local --json \
  --output /tmp/openclaw-live-smoke.mp3
 ```

-安全语音通话就绪冒烟测试：
+安全的语音通话就绪冒烟测试：

 ```bash
 pnpm openclaw voicecall setup --json
 pnpm openclaw voicecall smoke --to "+15555550123"
 ```

-`voicecall smoke` 默认是空运行，除非同时传入 `--yes`。只有在你有意发起真实通知通话时才使用 `--yes`。对于 Twilio、Telnyx 和
-Plivo，成功的就绪检查需要一个公网 webhook URL；按设计会拒绝仅本地
-loopback/私有回退。
+除非同时提供 `--yes`，否则 `voicecall smoke` 是一次空运行。只有在你有意发起真实通知通话时才使用 `--yes`。对于 Twilio、Telnyx 和 Plivo，成功的就绪检查需要一个公开的 webhook URL；按设计会拒绝仅本地的 loopback/私有回退。

-## Live：Android 节点能力扫描
+## 实时：Android 节点能力扫描

 - 测试：`src/gateway/android-node.capabilities.live.test.ts`
 - 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点 **当前公布的每一个命令**，并断言命令契约行为。
+- 目标：调用已连接 Android 节点**当前公布的每个命令**，并断言命令合约行为。
 - 范围：
-  - 需要预置条件/手动设置（该套件不会安装/运行/配对应用）。
-  - 对所选 Android 节点逐个命令进行 Gateway 网关 `node.invoke` 验证。
- 必需的预先设置：
-  - Android 应用已连接并配对到 Gateway 网关。
+  - 需预先满足条件/手动设置（该套件不会安装、运行或配对应用）。
+  - 针对所选 Android 节点逐个命令进行 Gateway 网关 `node.invoke` 验证。
+- 所需预设置：
+  - Android 应用已连接并已配对到 Gateway 网关。
  - 应用保持在前台。
-  - 已为你期望通过的能力授予权限/捕获同意。
+  - 对你期望通过的能力，已授予权限/捕获同意。
 - 可选目标覆盖：
  - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
  - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
 - 完整 Android 设置详情：[Android 应用](/zh-CN/platforms/android)

-## Live：模型冒烟测试（配置档密钥）
+## 实时：模型冒烟测试（配置文件密钥）

-Live 测试拆分为两层，便于我们隔离故障：
+实时测试分为两层，这样我们可以隔离失败：

- “直接模型”告诉我们，在给定密钥下该提供商/模型是否完全能回答。
- “Gateway 网关冒烟测试”告诉我们，该模型的完整 Gateway 网关+智能体流水线是否可用（会话、历史、工具、沙箱策略等）。
+- “直接模型”告诉我们，在给定密钥下，提供商/模型是否至少能回答。
+- “Gateway 网关冒烟测试”告诉我们，完整的 Gateway 网关 + 智能体流水线是否适用于该模型（会话、历史、工具、沙箱策略等）。

 ### 第 1 层：直接模型补全（无 Gateway 网关）

 - 测试：`src/agents/models.profiles.live.test.ts`
 - 目标：
  - 枚举发现的模型
-  - 使用 `getApiKeyForModel` 选择你已有凭证的模型
-  - 对每个模型运行一个小型补全（以及必要时的定向回归）
+  - 使用 `getApiKeyForModel` 选择你拥有凭证的模型
+  - 对每个模型运行一次小型补全（并在需要时运行定向回归）
 - 启用方式：
  - `pnpm test:live`（或在直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）以实际运行此套件；否则它会跳过，以保持 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
+- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，它是 modern 的别名）才会实际运行该套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
 - 选择模型的方式：
-  - `OPENCLAW_LIVE_MODELS=modern` 运行 modern 允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
-  - `OPENCLAW_LIVE_MODELS=all` 是 modern 允许列表的别名
-  - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗号分隔允许列表）
-  - Modern/all 扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行详尽 modern 扫描，或设置正数以使用更小上限。
-  - 详尽扫描会将 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 用作整个直接模型测试超时。默认值：60 分钟。
-  - 直接模型探测默认以 20 路并行运行；设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 可覆盖。
+  - `OPENCLAW_LIVE_MODELS=modern` 用于运行现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
+  - `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
+  - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗号允许列表）
+  - Modern/all 扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行穷尽式现代扫描，或设置正数以使用更小上限。
+  - 穷尽式扫描使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 作为整个直接模型测试的超时时间。默认值：60 分钟。
+  - 直接模型探测默认使用 20 路并行；设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 可覆盖。
 - 选择提供商的方式：
-  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔允许列表）
+  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号允许列表）
 - 密钥来源：
-  - 默认：配置档存储和环境变量回退
-  - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制 **仅使用配置档存储**
- 存在原因：
-  - 将“提供商 API 损坏/密钥无效”与“Gateway 网关智能体流水线损坏”分离
-  - 包含小型、隔离的回归（示例：OpenAI Responses/Codex Responses reasoning replay + 工具调用流程）
+  - 默认：配置文件存储和环境变量回退
+  - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制仅使用**配置文件存储**
+- 该项存在的原因：
+  - 将“提供商 API 已损坏/密钥无效”与“Gateway 网关智能体流水线已损坏”分离
+  - 包含小型、隔离的回归（示例：OpenAI Responses/Codex Responses 推理重放 + 工具调用流程）

-### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（“@openclaw”实际执行的内容）
+### 第 2 层：Gateway 网关 + 开发智能体冒烟测试（“@openclaw” 实际执行的内容）

 - 测试：`src/gateway/gateway-models.profiles.live.test.ts`
 - 目标：
  - 启动进程内 Gateway 网关
  - 创建/修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
-  - 遍历有密钥的模型并断言：
-    - “有意义的”响应（无工具）
-    - 真实工具调用可用（读取探测）
-    - 可选的额外工具探测（执行+读取探测）
-    - OpenAI 回归路径（仅工具调用 → 跟进）持续可用
- 探测详情（便于你快速解释故障）：
-  - `read` 探测：测试在工作区写入一个 nonce 文件，并要求智能体 `read` 它并回显 nonce。
-  - `exec+read` 探测：测试要求智能体通过 `exec` 将 nonce 写入临时文件，然后 `read` 回来。
-  - 图片探测：测试附加一张生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
+  - 遍历拥有密钥的模型并断言：
+    - “有意义”的响应（无工具）
+    - 真实工具调用可正常工作（读取探测）
+    - 可选的额外工具探测（执行 + 读取探测）
+    - OpenAI 回归路径（仅工具调用 → 后续轮次）保持正常
+- 探测详情（便于你快速解释失败）：
+  - `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 它且回显该 nonce。
+  - `exec+read` 探测：测试要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
+  - 图像探测：测试会附加一张生成的 PNG（cat + 随机代码），并期望模型返回 `cat <CODE>`。
  - 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
 - 启用方式：
  - `pnpm test:live`（或在直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
 - 选择模型的方式：
-  - 默认：modern 允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
-  - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern 允许列表的别名
+  - 默认：现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
+  - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
  - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）以缩小范围
-  - Modern/all Gateway 网关扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行详尽 modern 扫描，或设置正数以使用更小上限。
- 选择提供商的方式（避免“OpenRouter everything”）：
-  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔允许列表）
- 工具 + 图片探测在此 live 测试中始终开启：
+  - Modern/all Gateway 网关扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行穷尽式现代扫描，或设置正数以使用更小上限。
+- 选择提供商的方式（避免“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>" }]` 发送
+    - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送它
    - Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
    - 嵌入式智能体将多模态用户消息转发给模型
    - 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）

 <Tip>
-要查看你的机器上可以测试什么（以及精确的 `provider/model` id），请运行：
+要查看你的机器上可以测试什么（以及确切的 `provider/model` ID），请运行：

 ```bash
 openclaw models list
@ -143,27 +138,27 @@ openclaw models list --json

 </Tip>

-## Live：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
+## 实时：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）

 - 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线，且不触碰你的默认配置。
- 后端特定的冒烟测试默认值位于所属插件的 `cli-backend.ts` 定义中。
+- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线，而不触碰你的默认配置。
+- 后端特定的冒烟测试默认值随所属插件的 `cli-backend.ts` 定义一起提供。
 - 启用：
  - `pnpm test:live`（或在直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
  - `OPENCLAW_LIVE_CLI_BACKEND=1`
 - 默认值：
  - 默认提供商/模型：`claude-cli/claude-sonnet-4-6`
-  - 命令/参数/图片行为来自所属 CLI 后端插件元数据。
+  - 命令/参数/图像行为来自所属 CLI 后端插件元数据。
 - 覆盖（可选）：
  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
  - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
  - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
-  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图片附件（路径会注入到提示中）。Docker 配方默认关闭此项，除非显式请求。
-  - `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_MODEL_SWITCH_PROBE=1` 当所选模型支持切换目标时，选择加入 Claude Sonnet -> Opus 同会话连续性探测。Docker 配方为聚合可靠性默认关闭此项。
-  - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 选择加入 MCP/工具 loopback 探测。Docker 配方默认关闭此项，除非显式请求。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 用于发送真实图像附件（路径会注入到提示中）。除非明确请求，否则 Docker 配方默认关闭此项。
+  - `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_MODEL_SWITCH_PROBE=1` 用于在所选模型支持切换目标时选择加入 Claude Sonnet -> Opus 同会话连续性探测。为保证聚合可靠性，Docker 配方默认关闭此项。
+  - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 用于选择加入 MCP/工具 loopback 探测。除非明确请求，否则 Docker 配方默认关闭此项。

 示例：

@ -180,9 +175,7 @@ OPENCLAW_LIVE_TEST=1 \
  pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
 ```

-这不会要求 Gemini 生成响应。它会写入 OpenClaw 提供给 Gemini 的相同系统
-设置，然后运行 `gemini --debug mcp list`，以证明已保存的 `transport: "streamable-http"` 服务器会规范化为 Gemini 的 HTTP MCP
-形态，并且可以连接到本地 streamable-HTTP MCP 服务器。
+这不会要求 Gemini 生成响应。它会写入 OpenClaw 提供给 Gemini 的相同系统设置，然后运行 `gemini --debug mcp list`，以证明保存的 `transport: "streamable-http"` 服务器会规范化为 Gemini 的 HTTP MCP 形态，并且可以连接到本地 streamable-HTTP MCP 服务器。

 Docker 配方：

@ -202,27 +195,36 @@ pnpm test:docker:live-cli-backend:gemini
 说明：

 - Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
- 它以非 root `node` 用户在仓库 Docker 镜像内运行 live CLI 后端冒烟测试。
- 它从所属插件解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（默认：`~/.cache/openclaw/docker-cli-tools`）处的可写缓存前缀中。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json` 或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供可移植的 Claude Code 订阅 OAuth。它先在 Docker 中证明直接 `claude -p` 可用，然后在不保留 Anthropic API-key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端。该订阅通道默认禁用 Claude MCP/工具和图片探测，因为 Claude 目前将第三方应用使用量路由到额外用量计费，而不是正常订阅计划限额。
- live CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮、图片分类轮，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得早先的备注。
+- 它会在仓库 Docker 镜像内以非 root 的 `node` 用户运行实时 CLI 后端冒烟测试。
+- 它会从所属插件解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到位于 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 的缓存可写前缀中（默认值：`~/.cache/openclaw/docker-cli-tools`）。
+- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json` 或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中证明直接 `claude -p` 可用，然后在不保留 Anthropic API key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端。此订阅通道默认禁用 Claude MCP/工具和图像探测，因为 Claude 当前会将第三方应用使用量路由到额外使用量计费，而不是普通订阅计划限额。
+- 实时 CLI 后端冒烟测试现在会为 Claude、Codex 和 Gemini 运行相同的端到端流程：文本轮次、图像分类轮次，然后是通过 Gateway 网关 CLI 验证的 MCP `cron` 工具调用。
+- Claude 的默认冒烟测试还会将会话从 Sonnet 修补到 Opus，并验证恢复后的会话仍然记得之前的备注。

-## Live：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
+## 实时：APNs HTTP/2 代理可达性
+
+- 测试：`src/infra/push-apns-http2.live.test.ts`
+- 目标：通过本地 HTTP CONNECT 代理隧道连接到 Apple 的沙箱 APNs 端点，发送 APNs HTTP/2 验证请求，并断言 Apple 的真实 `403 InvalidProviderToken` 响应会通过该代理路径返回。
+- 启用：
+  - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
+- 可选超时：
+  - `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`
+
+## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）

 - 测试：`src/gateway/gateway-acp-bind.live.test.ts`
- 目标：使用实时 ACP 智能体验证真实的 ACP 会话绑定流程：
+- 目标：使用实时 ACP 智能体验证真实的 ACP conversation-bind 流程：
  - 发送 `/acp spawn <agent> --bind here`
-  - 在原地绑定一个合成的消息渠道会话
-  - 在同一个会话上发送普通的后续消息
-  - 验证该后续消息落入已绑定 ACP 会话的转录中
+  - 就地绑定一个合成的消息渠道对话
+  - 在同一对话上发送普通的后续消息
+  - 验证后续消息落入绑定的 ACP 会话 transcript
 - 启用：
  - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
  - `OPENCLAW_LIVE_ACP_BIND=1`
 - 默认值：
  - Docker 中的 ACP 智能体：`claude,codex,gemini`
  - 直接运行 `pnpm test:live ...` 时使用的 ACP 智能体：`claude`
-  - 合成渠道：Slack 私信风格的会话上下文
+  - 合成渠道：Slack 私信风格的对话上下文
  - ACP 后端：`acpx`
 - 覆盖项：
  - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@ -238,9 +240,9 @@ pnpm test:docker:live-cli-backend:gemini
  - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
  - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
 - 说明：
-  - 此测试线使用 Gateway 网关 `chat.send` 表面以及仅限管理员的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而不必假装向外部投递。
-  - 未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件的内置智能体注册表来选择 ACP harness 智能体。
-  - 默认情况下，已绑定会话的 cron MCP 创建会尽力执行，因为外部 ACP harness 可能会在绑定/图像证明通过后取消 MCP 调用；设置 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可让绑定后的 cron 探测变为严格模式。
+  - 这个通道使用 Gateway 网关的 `chat.send` surface，并带有仅管理员可用的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而不必伪装成向外部投递。
+  - 未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会为所选 ACP harness 智能体使用嵌入式 `acpx` 插件的内置智能体注册表。
+  - 绑定会话的 cron MCP 创建默认是尽力而为，因为外部 ACP harness 可能会在 bind/image 证明通过后取消 MCP 调用；设置 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可让 bind 后的 cron 探测变为严格模式。

 示例：

@ -268,31 +270,31 @@ pnpm test:docker:live-acp-bind:opencode

 Docker 说明：

- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 默认情况下，它会按顺序针对聚合的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 来缩小矩阵范围。
- 它会加载 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、通过 `https://app.factory.ai/cli` 安装的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 后端本身是官方 `acpx` 插件中嵌入的 `acpx/runtime` 包。
- Droid Docker 变体会暂存 `~/.factory` 作为设置，转发 `FACTORY_API_KEY`，并且需要该 API key，因为本地 Factory OAuth/keyring 认证无法移植到容器中。它使用 ACPX 内置的 `droid exec --output-format acp` 注册表条目。
- OpenCode Docker 变体是严格的单智能体回归测试线。它在加载 `~/.profile` 后，根据 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（默认 `opencode/kimi-k2.6`）写入临时 `OPENCODE_CONFIG_CONTENT` 默认模型，并且 `pnpm test:docker:live-acp-bind:opencode` 要求存在已绑定助手转录，而不是接受通用的绑定后跳过。
- 直接调用 `acpx` CLI 仅是用于比较 Gateway 网关外部行为的手动/变通路径。Docker ACP 绑定冒烟测试会运行 OpenClaw 嵌入的 `acpx` 运行时后端。
+- Docker runner 位于 `scripts/test-live-acp-bind-docker.sh`。
+- 默认情况下，它会按顺序针对聚合的实时 CLI 智能体运行 ACP bind 冒烟测试：`claude`、`codex`，然后是 `gemini`。
+- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 来缩小矩阵。
+- 它会 source `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、通过 `https://app.factory.ai/cli` 安装的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 后端本身是来自官方 `acpx` 插件的嵌入式 `acpx/runtime` 包。
+- Droid Docker 变体会暂存 `~/.factory` 用于设置，转发 `FACTORY_API_KEY`，并且要求该 API key，因为本地 Factory OAuth/keyring 认证无法移植到容器中。它使用 ACPX 的内置 `droid exec --output-format acp` 注册表条目。
+- OpenCode Docker 变体是一个严格的单智能体回归通道。它在 source `~/.profile` 后，从 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（默认 `opencode/kimi-k2.6`）写入一个临时 `OPENCODE_CONFIG_CONTENT` 默认模型，并且 `pnpm test:docker:live-acp-bind:opencode` 要求存在绑定的助手 transcript，而不是接受通用的 bind 后跳过。
+- 直接 `acpx` CLI 调用仅是用于在 Gateway 网关之外比较行为的手动/变通路径。Docker ACP bind 冒烟测试会测试 OpenClaw 嵌入式 `acpx` 运行时后端。

 ## 实时：Codex app-server harness 冒烟测试

 - 目标：通过正常的 Gateway 网关 `agent` 方法验证插件拥有的 Codex harness：
-  - 加载内置的 `codex` 插件
+  - 加载内置 `codex` 插件
  - 选择 `OPENCLAW_AGENT_RUNTIME=codex`
-  - 向 `openai/gpt-5.5` 发送第一个 Gateway 网关智能体轮次，并强制使用 Codex harness
-  - 向同一个 OpenClaw 会话发送第二个轮次，并验证 app-server 线程可以恢复
+  - 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.5` 发送第一个 Gateway 网关智能体回合
+  - 向同一个 OpenClaw 会话发送第二个回合，并验证 app-server thread 可以恢复
  - 通过同一个 Gateway 网关命令路径运行 `/codex status` 和 `/codex models`
-  - 可选运行两个经 Guardian 审核的提升权限 shell 探测：一个应获批准的无害命令，以及一个应被拒绝的虚假密钥上传，以便智能体回问
+  - 可选运行两个经过 Guardian 审核的提权 shell 探测：一个应被批准的无害命令，以及一个应被拒绝的伪密钥上传，以便智能体反问
 - 测试：`src/gateway/gateway-codex-harness.live.test.ts`
 - 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
 - 默认模型：`openai/gpt-5.5`
- 可选图像探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP/工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
+- 可选图片探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
+- 可选 MCP/tool 探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
 - 可选 Guardian 探测：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- 该冒烟测试使用 `agentRuntime.id: "codex"`，因此损坏的 Codex harness 无法通过静默回退到 PI 而通过。
- 凭证：来自本地 Codex 订阅登录的 Codex app-server 认证。Docker 冒烟测试在适用时也可以为非 Codex 探测提供 `OPENAI_API_KEY`，并可选择复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
+- 冒烟测试使用 `agentRuntime.id: "codex"`，因此损坏的 Codex harness 不能通过静默回退到 PI 来通过。
+- 认证：来自本地 Codex 订阅登录的 Codex app-server 认证。Docker 冒烟测试在适用时也可以为非 Codex 探测提供 `OPENAI_API_KEY`，以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。

 本地配方：

@ -315,22 +317,22 @@ pnpm test:docker:live-codex-harness

 Docker 说明：

- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
- 它会加载已挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI 认证文件，将 `@openai/codex` 安装到可写的已挂载 npm 前缀中，暂存源码树，然后只运行 Codex harness 实时测试。
- Docker 默认启用图像、MCP/工具和 Guardian 探测。当你需要更窄的调试运行时，设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 使用相同的显式 Codex 运行时配置，因此旧别名或 PI 回退无法隐藏 Codex harness 回归。
+- Docker runner 位于 `scripts/test-live-codex-harness-docker.sh`。
+- 它会 source 挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI 认证文件，将 `@openai/codex` 安装到可写的挂载 npm prefix 中，暂存源代码树，然后只运行 Codex-harness 实时测试。
+- Docker 默认启用图片、MCP/tool 和 Guardian 探测。当你需要更窄的调试运行时，设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
+- Docker 使用同样显式的 Codex 运行时配置，因此旧别名或 PI 回退无法隐藏 Codex harness 回归。

 ### 推荐的实时配方

-范围窄且显式的允许列表最快，也最不易波动：
+窄范围、显式的允许列表最快且最不容易不稳定：

- 单个模型，直接运行（无 Gateway 网关）：
+- 单模型，直接运行（无 Gateway 网关）：
  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`

- 单个模型，Gateway 网关冒烟测试：
+- 单模型，Gateway 网关冒烟测试：
  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

- 跨多个提供商的工具调用：
+- 跨多个提供商的 tool calling：
  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

 - Google 重点测试（Gemini API key + Antigravity）：
@ -338,26 +340,26 @@ Docker 说明：
  - 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 adaptive thinking 冒烟测试：
-  - 如果本地密钥位于 shell profile 中：`source ~/.profile`
+  - 如果本地 keys 存在于 shell profile 中：`source ~/.profile`
  - Gemini 3 动态默认值：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
  - Gemini 2.5 动态预算：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`

 说明：

 - `google/...` 使用 Gemini API（API key）。
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具差异）。
- Gemini API 与 Gemini CLI：
-  - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；这是多数用户所说的 “Gemini”。
-  - CLI：OpenClaw 调用本地 `gemini` 二进制文件；它有自己的认证，并且行为可能不同（流式传输/工具支持/版本偏差）。
+- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。
+- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + tooling 差异）。
+- Gemini API vs Gemini CLI：
+  - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile auth）；这就是大多数用户所说的 “Gemini”。
+  - CLI：OpenClaw shell 到本地 `gemini` binary；它有自己的认证，并且行为可能不同（streaming/tool 支持/版本偏差）。

 ## 实时：模型矩阵（覆盖范围）

-没有固定的 “CI 模型列表”（实时测试是选择性启用），但以下是建议在有密钥的开发机器上定期覆盖的**推荐**模型。
+没有固定的 “CI 模型列表”（实时测试是 opt-in），但这些是建议在具备 keys 的开发机器上定期覆盖的**推荐**模型。

-### 现代冒烟集合（工具调用 + 图像）
+### 现代冒烟集合（tool calling + 图片）

-这是我们期望持续可用的“常用模型”运行：
+这是我们期望保持可用的 “常用模型” 运行：

 - OpenAI（非 Codex）：`openai/gpt-5.5`
 - OpenAI Codex OAuth：`openai-codex/gpt-5.5`
@ -368,10 +370,10 @@ Docker 说明：
 - Z.AI（GLM）：`zai/glm-5.1`
 - MiniMax：`minimax/MiniMax-M2.7`

-运行带工具 + 图像的 Gateway 网关冒烟测试：
+使用工具 + 图片运行 Gateway 网关冒烟测试：
 `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

-### 基线：工具调用（Read + 可选 Exec）
+### 基线：tool calling（Read + 可选 Exec）

 每个提供商家族至少选择一个：

@ -382,48 +384,48 @@ Docker 说明：
 - Z.AI（GLM）：`zai/glm-5.1`
 - MiniMax：`minimax/MiniMax-M2.7`

-可选的额外覆盖范围（建议具备）：
+可选的额外覆盖（值得拥有）：

 - xAI：`xai/grok-4.3`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用且支持“工具”的模型）
+- Mistral：`mistral/`…（选择一个你已启用的支持 “tools” 的模型）
 - Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
+- LM Studio：`lmstudio/`…（本地；tool calling 取决于 API mode）

-### 视觉：图像发送（附件 → 多模态消息）
+### 视觉：图片发送（附件 → 多模态消息）

-在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含至少一个支持图像的模型（Claude/Gemini/OpenAI 中支持视觉的变体等），以运行图像探测。
+在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图片的模型（Claude/Gemini/OpenAI 的 vision-capable 变体等），以测试图片探测。

-### 聚合器 / 备用 Gateway 网关
+### 聚合器 / 替代 Gateway 网关

-如果你已启用密钥，我们也支持通过以下方式测试：
+如果你已启用 keys，我们也支持通过以下方式测试：

- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具+图像的候选模型）
+- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找具备 tool+image 能力的候选项）
 - OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）

-你可以纳入实时矩阵的更多提供商（如果你有凭证/配置）：
+你可以加入实时矩阵的更多提供商（如果你有凭据/配置）：

 - 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等）
+- 通过 `models.providers`（自定义端点）：`minimax`（cloud/API），以及任何 OpenAI/Anthropic-compatible proxy（LM Studio、vLLM、LiteLLM 等）

 <Tip>
-不要在文档中硬编码 “所有模型”。权威列表是你机器上 `discoverModels(...)` 返回的内容，加上可用的密钥。
+不要在文档中硬编码 “all models”。权威列表是你的机器上 `discoverModels(...)` 返回的内容，以及可用的 keys。
 </Tip>

-## 凭证（绝不要提交）
+## 凭据（切勿提交）

-实时测试会以 CLI 相同的方式发现凭证。实际影响：
+实时测试会以与 CLI 相同的方式发现凭据。实际影响：

- 如果 CLI 可用，实时测试应该能找到相同的密钥。
- 如果实时测试提示“no creds”，按调试 `openclaw models list` / 模型选择的相同方式调试。
+- 如果 CLI 正常工作，实时测试应该能找到相同的密钥。
+- 如果实时测试显示“没有凭证”，请按调试 `openclaw models list` / 模型选择的方式来调试。

- 每个智能体的身份验证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中“profile keys”的含义）
+- 每智能体身份验证配置档案：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中“配置档案密钥”的含义）
 - 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试主目录中，但不是主要的 profile-key 存储）
- 本地实时运行默认会将活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/`，以及支持的外部 CLI 身份验证目录复制到临时测试主目录；暂存的实时主目录会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以便探测不会触碰你真实主机上的工作区。
+- 旧版状态目录：`~/.openclaw/credentials/`（存在时会被复制到暂存的实时主目录，但不是主要的配置档案密钥存储）
+- 本地实时运行默认会把活跃配置、每智能体的 `auth-profiles.json` 文件、旧版 `credentials/`，以及受支持的外部 CLI 身份验证目录复制到临时测试主目录；暂存的实时主目录会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以便探测不会访问你的真实主机工作区。

-如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出），请在 `source ~/.profile` 后运行本地测试，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
+如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出的密钥），请在 `source ~/.profile` 后运行本地测试，或使用下面的 Docker runner（它们可以把 `~/.profile` 挂载到容器中）。

-## Deepgram 实时（音频转写）
+## Deepgram 实时（音频转录）

 - 测试：`extensions/deepgram/audio.live.test.ts`
 - 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
@ -439,9 +441,9 @@ Docker 说明：
 - 测试：`extensions/comfy/comfy.live.test.ts`
 - 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
 - 范围：
-  - 覆盖内置的 comfy 图像、视频和 `music_generate` 路径
+  - 执行内置的 comfy 图像、视频和 `music_generate` 路径
  - 除非已配置 `plugins.entries.comfy.config.<capability>`，否则跳过每项能力
-  - 适用于更改 comfy 工作流提交、轮询、下载或插件注册后
+  - 在更改 comfy 工作流提交、轮询、下载或插件注册后很有用

 ## 图像生成实时测试

@ -451,8 +453,8 @@ Docker 说明：
 - 范围：
  - 枚举每个已注册的图像生成提供商插件
  - 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
-  - 默认优先使用实时/环境 API 密钥，而不是已存储的身份验证配置文件，因此 `auth-profiles.json` 中的陈旧测试密钥不会掩盖真实的 shell 凭据
-  - 跳过没有可用身份验证/配置文件/模型的提供商
+  - 默认优先使用实时/环境变量 API key，而不是存储的身份验证配置档案，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
+  - 跳过没有可用身份验证/配置档案/模型的提供商
  - 通过共享图像生成运行时运行每个已配置的提供商：
    - `<provider>:generate`
    - 当提供商声明支持编辑时运行 `<provider>:edit`
@ -471,9 +473,9 @@ Docker 说明：
  - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
  - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
 - 可选身份验证行为：
-  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置文件存储身份验证，并忽略仅环境变量的覆盖
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置档案存储身份验证，并忽略仅环境变量的覆盖

-对于已发布的 CLI 路径，在提供商/运行时实时测试通过后添加一个 `infer` 冒烟测试：
+对于已发布的 CLI 路径，请在提供商/运行时实时测试通过后添加一个 `infer` 冒烟测试：

 ```bash
 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@ -493,23 +495,23 @@ openclaw infer image generate \
 - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
 - Harness：`pnpm test:live:media music`
 - 范围：
-  - 覆盖共享的内置音乐生成提供商路径
+  - 执行共享的内置音乐生成提供商路径
  - 当前覆盖 Google 和 MiniMax
  - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
-  - 默认优先使用实时/环境 API 密钥，而不是已存储的身份验证配置文件，因此 `auth-profiles.json` 中的陈旧测试密钥不会掩盖真实的 shell 凭据
-  - 跳过没有可用身份验证/配置文件/模型的提供商
-  - 可用时运行两种声明的运行时模式：
-    - 使用仅提示词输入的 `generate`
+  - 默认优先使用实时/环境变量 API key，而不是存储的身份验证配置档案，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
+  - 跳过没有可用身份验证/配置档案/模型的提供商
+  - 可用时运行两个已声明的运行时模式：
+    - 使用仅提示输入运行 `generate`
    - 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
  - 当前共享通道覆盖范围：
    - `google`：`generate`、`edit`
    - `minimax`：`generate`
-    - `comfy`：单独的 Comfy 实时文件，不在此共享扫描中
+    - `comfy`：单独的 Comfy 实时文件，不属于这次共享扫描
 - 可选缩小范围：
  - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
  - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
 - 可选身份验证行为：
-  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置文件存储身份验证，并忽略仅环境变量的覆盖
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置档案存储身份验证，并忽略仅环境变量的覆盖

 ## 视频生成实时测试

@ -517,43 +519,43 @@ openclaw infer image generate \
 - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
 - Harness：`pnpm test:live:media video`
 - 范围：
-  - 覆盖共享的内置视频生成提供商路径
-  - 默认使用适合发布的冒烟路径：非 FAL 提供商、每个提供商一次文本转视频请求、一秒钟龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每个提供商操作上限（默认 `180000`）
-  - 默认跳过 FAL，因为提供商侧队列延迟可能会主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
+  - 执行共享的内置视频生成提供商路径
+  - 默认使用发布安全的冒烟路径：非 FAL 提供商、每个提供商一次文本转视频请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`）
+  - 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
  - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
-  - 默认优先使用实时/环境 API 密钥，而不是已存储的身份验证配置文件，因此 `auth-profiles.json` 中的陈旧测试密钥不会掩盖真实的 shell 凭据
-  - 跳过没有可用身份验证/配置文件/模型的提供商
-  - 默认只运行 `generate`
-  - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，也会在可用时运行声明的转换模式：
-    - 当提供商声明 `capabilities.imageToVideo.enabled`，并且所选提供商/模型在共享扫描中接受由 buffer 支持的本地图像输入时，运行 `imageToVideo`
-    - 当提供商声明 `capabilities.videoToVideo.enabled`，并且所选提供商/模型在共享扫描中接受由 buffer 支持的本地视频输入时，运行 `videoToVideo`
-  - 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商：
-    - `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
-  - 提供商特定的 Vydra 覆盖范围：
+  - 默认优先使用实时/环境变量 API key，而不是存储的身份验证配置档案，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
+  - 跳过没有可用身份验证/配置档案/模型的提供商
+  - 默认仅运行 `generate`
+  - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，也会在可用时运行已声明的转换模式：
+    - 当提供商声明 `capabilities.imageToVideo.enabled`，并且所选提供商/模型在共享扫描中接受由缓冲区支持的本地图像输入时，运行 `imageToVideo`
+    - 当提供商声明 `capabilities.videoToVideo.enabled`，并且所选提供商/模型在共享扫描中接受由缓冲区支持的本地视频输入时，运行 `videoToVideo`
+  - 当前共享扫描中已声明但跳过的 `imageToVideo` 提供商：
+    - `vydra`，因为内置的 `veo3` 仅支持文本，而内置的 `kling` 需要远程图像 URL
+  - Vydra 提供商专属覆盖：
    - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
-    - 该文件运行 `veo3` 文本转视频，以及默认使用远程图像 URL fixture 的 `kling` 通道
-  - 当前 `videoToVideo` 实时覆盖范围：
+    - 该文件会运行 `veo3` 文本转视频，以及一个默认使用远程图像 URL fixture 的 `kling` 通道
+  - 当前 `videoToVideo` 实时覆盖：
    - 仅当所选模型为 `runway/gen4_aleph` 时覆盖 `runway`
-  - 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商：
-    - `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
-    - `google`，因为当前共享的 Gemini/Veo 通道使用由本地 buffer 支持的输入，而共享扫描不接受该路径
-    - `openai`，因为当前共享通道缺少特定组织的视频修复/混剪访问保证
+  - 当前共享扫描中已声明但跳过的 `videoToVideo` 提供商：
+    - `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 引用 URL
+    - `google`，因为当前共享 Gemini/Veo 通道使用由本地缓冲区支持的输入，而共享扫描不接受该路径
+    - `openai`，因为当前共享通道缺少组织专属视频修复/重混访问保证
 - 可选缩小范围：
  - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
  - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
  - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 用于在默认扫描中包含每个提供商，包括 FAL
-  - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 用于在激进的冒烟运行中降低每个提供商的操作上限
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 用于为激进的冒烟运行降低每个提供商的操作上限
 - 可选身份验证行为：
-  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置文件存储身份验证，并忽略仅环境变量的覆盖
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置档案存储身份验证，并忽略仅环境变量的覆盖

 ## 媒体实时 Harness

 - 命令：`pnpm test:live:media`
- 目的：
+- 用途：
  - 通过一个仓库原生入口点运行共享的图像、音乐和视频实时套件
  - 从 `~/.profile` 自动加载缺失的提供商环境变量
  - 默认自动将每个套件缩小到当前拥有可用身份验证的提供商
-  - 复用 `scripts/test-live.mjs`，因此 Heartbeat 和安静模式行为保持一致
+  - 复用 `scripts/test-live.mjs`，因此 Heartbeat 和静默模式行为保持一致
 - 示例：
  - `pnpm test:live:media`
  - `pnpm test:live:media image video --providers openai,google,minimax`
--- a/docs/zh-CN/security/network-proxy.md
+++ b/docs/zh-CN/security/network-proxy.md
@ -1,40 +1,40 @@
 ---
 read_when:
-    - 你希望针对 SSRF 和 DNS 重绑定攻击进行深度防御
+    - 你希望针对 SSRF 和 DNS 重绑定攻击提供纵深防御
    - 为 OpenClaw 运行时流量配置外部正向代理
-summary: 如何通过运营方管理的过滤代理路由 OpenClaw 运行时 HTTP 和 WebSocket 流量
+summary: 如何将 OpenClaw 运行时的 HTTP 和 WebSocket 流量经由操作方管理的过滤代理进行路由
 title: 网络代理
 x-i18n:
-    generated_at: "2026-05-04T03:58:51Z"
+    generated_at: "2026-05-04T11:08:49Z"
    model: gpt-5.5
    provider: openai
-    source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
+    source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
    source_path: security/network-proxy.md
    workflow: 16
 ---

 # 网络代理

-OpenClaw 可以通过由操作方管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于希望集中控制出口流量、增强 SSRF 保护并提升网络可审计性的部署，这是可选的纵深防御措施。
+OpenClaw 可以通过运维方管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于希望集中控制出口流量、加强 SSRF 防护并提升网络审计能力的部署来说，这是一种可选的纵深防御措施。

 OpenClaw 不会附带、下载、启动、配置或认证代理。你运行适合自己环境的代理技术，OpenClaw 会通过它路由普通的进程本地 HTTP 和 WebSocket 客户端。

 ## 为什么使用代理？

-代理为操作方提供一个针对出站 HTTP 和 WebSocket 流量的网络控制点。即使不用于 SSRF 加固，这也很有用：
+代理为运维方提供一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使不考虑 SSRF 加固，这也很有用：

 - 集中策略：维护一套出口策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。
- 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标。
- DNS 重绑定防护：缩小应用级 DNS 检查与实际出站连接之间的间隙。
- 更广泛的 JavaScript 覆盖：通过同一路径路由普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端。
- 可审计性：在出口边界记录被允许和被拒绝的目标。
- 运维控制：无需重新构建 OpenClaw，即可强制执行目标规则、网络分段、速率限制或出站允许列表。
+- 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标地址。
+- DNS 重新绑定防御：缩小应用级 DNS 检查与实际出站连接之间的空隙。
+- 更广泛的 JavaScript 覆盖：将普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端路由到同一路径。
+- 可审计性：在出口边界记录允许和拒绝的目标。
+- 运维控制：无需重新构建 OpenClaw，就能强制执行目标规则、网络分段、速率限制或出站允许列表。

-代理路由是普通 HTTP 和 WebSocket 出口的进程级护栏。它为操作方提供一条故障关闭路径，用于通过他们自己的过滤代理路由受支持的 JavaScript HTTP 客户端，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证代理的目标策略。
+代理路由是普通 HTTP 和 WebSocket 出口的进程级护栏。它为运维方提供了一条故障关闭路径，用于将受支持的 JavaScript HTTP 客户端路由到他们自己的过滤代理，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证代理的目标策略。

 ## OpenClaw 如何路由流量

-当 `proxy.enabled=true` 且已配置代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过已配置的代理路由普通 HTTP 和 WebSocket 出口流量：
+当 `proxy.enabled=true` 且配置了代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出口：

 ```text
 OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
  WebSocket clients      -> operator-managed filtering proxy -> public internet
 ```

-公开契约是路由行为，而不是用于实现它的内部 Node 钩子。当 Gateway 网关 URL 使用 `localhost` 或字面量 loopback IP（例如 `127.0.0.1` 或 `[::1]`）时，OpenClaw Gateway 网关控制平面 WebSocket 客户端会为 local loopback Gateway 网关 RPC 流量使用一条狭窄的直连路径。即使操作方代理阻止 loopback 目标，该控制平面路径也必须能够访问 loopback Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍会使用已配置的代理。
+公开契约是路由行为，而不是用于实现它的内部 Node 钩子。当 Gateway 网关 URL 使用 `localhost` 或字面量环回 IP（例如 `127.0.0.1` 或 `[::1]`）时，OpenClaw Gateway 网关控制平面 WebSocket 客户端会为 local loopback Gateway 网关 RPC 流量使用一条狭窄的直连路径。即使运维方代理阻止环回目标，该控制平面路径也必须能够访问环回 Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍会使用配置的代理。

 在内部，OpenClaw 为此功能使用两个进程级路由钩子：

- Undici dispatcher 路由覆盖 `fetch`、基于 undici 的客户端，以及提供其自身 undici dispatcher 的传输。
- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多构建在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的库。托管代理模式会强制使用该全局 agent，因此显式 Node HTTP agent 不会意外绕过操作方代理。
+- Undici dispatcher 路由覆盖 `fetch`、基于 undici 的客户端，以及提供自身 undici dispatcher 的传输协议。
+- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多构建在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的库。托管代理模式会强制使用该全局 agent，这样显式 Node HTTP agent 不会意外绕过运维方代理。

-某些插件拥有自定义传输，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输使用自己的 HTTP/1 undici dispatcher，因此会在该所有者特定的传输路径中遵循进程代理环境变量，以及托管的 `OPENCLAW_PROXY_URL` 回退。
+一些插件拥有自定义传输协议，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输协议使用自己的 HTTP/1 undici dispatcher，因此会在该 owner 专用传输路径中遵循进程代理环境以及托管的 `OPENCLAW_PROXY_URL` 回退。

-代理 URL 本身必须使用 `http://`。HTTPS 目标仍可通过带有 HTTP `CONNECT` 的代理支持；这只表示 OpenClaw 期望一个纯 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。
+代理 URL 本身必须使用 `http://`。HTTPS 目标仍支持通过代理使用 HTTP `CONNECT`；这只表示 OpenClaw 期望一个普通 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。

-代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表是基于目标的，因此如果其中保留 `localhost` 或 `127.0.0.1`，高风险 SSRF 目标就会绕过过滤代理。
+代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标地址，因此如果将 `localhost` 或 `127.0.0.1` 留在那里，高风险 SSRF 目标就能跳过过滤代理。

-关闭时，OpenClaw 会恢复先前的代理环境，并重置缓存的进程路由状态。
+关闭时，OpenClaw 会恢复之前的代理环境，并重置缓存的进程路由状态。

 ## 相关代理术语

- `proxy.enabled` / `proxy.proxyUrl`：用于 OpenClaw 运行时出口的出站正向代理路由。本页记录该功能。
- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理认证。请参阅[受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)。
- `openclaw proxy`：用于开发和支持的本地调试代理和捕获检查器。请参阅 [openclaw proxy](/zh-CN/cli/proxy)。
- 渠道或提供商特定代理设置：针对特定传输的所有者特定覆盖。当目标是在整个运行时中进行集中出口控制时，优先使用托管网络代理。
+- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 运行时出口的出站正向代理路由。本页介绍此功能。
+- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理认证。参见[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。
+- `openclaw proxy`：用于开发和支持的本地调试代理和捕获检查器。参见 [openclaw proxy](/zh-CN/cli/proxy)。
+- 渠道或提供商专用代理设置：特定传输协议的 owner 专用覆盖。当目标是在整个运行时集中控制出口流量时，优先使用托管网络代理。

 ## 配置

@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run

 `proxy.proxyUrl` 优先于 `OPENCLAW_PROXY_URL`。

-如果 `enabled=true` 但未配置有效的代理 URL，受保护的命令会在启动时失败，而不是回退到直接网络访问。
+如果 `enabled=true` 但未配置有效的代理 URL，受保护命令会启动失败，而不是回退到直接网络访问。

 对于使用 `openclaw gateway start` 启动的托管 Gateway 网关服务，建议将 URL 存储在配置中：

@ -92,63 +92,63 @@ openclaw gateway install --force
 openclaw gateway start
 ```

-环境回退最适合前台运行。如果将其用于已安装的服务，请将 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装服务，使 launchd、systemd 或 Scheduled Tasks 使用该值启动 Gateway 网关。
+环境回退最适合前台运行。如果你将它用于已安装的服务，请将 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装服务，让 launchd、systemd 或 Scheduled Tasks 使用该值启动 Gateway 网关。

-对于 `openclaw --container ...` 命令，设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将其转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器本身，而不是主机。除非你显式覆盖该安全检查，否则 OpenClaw 会拒绝面向容器命令中的 loopback 代理 URL。
+对于 `openclaw --container ...` 命令，当设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将它转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器自身，而不是主机。除非你显式覆盖该安全检查，否则 OpenClaw 会拒绝面向容器命令的环回代理 URL。

 ## 代理要求

 代理策略是安全边界。OpenClaw 无法验证代理是否阻止了正确的目标。

-配置代理以：
+请将代理配置为：

- 仅绑定到 loopback 或私有受信任接口。
- 限制访问，使只有 OpenClaw 进程、主机、容器或服务账户可以使用它。
+- 仅绑定到环回或可信的私有接口。
+- 限制访问，使只有 OpenClaw 进程、主机、容器或服务账号可以使用它。
 - 自行解析目标，并在 DNS 解析后阻止目标 IP。
- 在连接时对纯 HTTP 请求和 HTTPS `CONNECT` 隧道应用策略。
- 拒绝针对 loopback、私有、链路本地、元数据、多播、保留或文档地址范围的基于目标的绕过。
- 避免主机名允许列表，除非你完全信任 DNS 解析路径。
- 记录目标、决策、状态和原因，但不记录请求正文、授权标头、cookie 或其他密钥。
- 将代理策略置于版本控制之下，并像审查安全敏感配置一样审查变更。
+- 对普通 HTTP 请求和 HTTPS `CONNECT` 隧道都在连接时应用策略。
+- 拒绝针对环回、私有、链路本地、元数据、多播、保留或文档范围的基于目标的绕过。
+- 除非你完全信任 DNS 解析路径，否则避免使用主机名允许列表。
+- 记录目标、决策、状态和原因，但不要记录请求正文、授权标头、Cookie 或其他机密。
+- 将代理策略置于版本控制之下，并像审查安全敏感配置一样审查更改。

 ## 建议阻止的目标

 将此拒绝列表作为任何正向代理、防火墙或出口策略的起点。

-OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的对等钩子是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及针对 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵处理。维护外部代理策略时，这些文件是有用的参考，但 OpenClaw 不会自动在你的代理中导出或强制执行这些规则。
+OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的对等钩子包括 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及用于 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵处理。这些文件在维护外部代理策略时是有用的参考，但 OpenClaw 不会自动导出这些规则或在你的代理中强制执行它们。

-| 范围或主机                                                                         | 阻止原因                                             |
+| 范围或主机                                                                        | 阻止原因                                             |
 | ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
-| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                  | IPv4 loopback                                        |
-| `::1/128`                                                                            | IPv6 loopback                                        |
-| `0.0.0.0/8`, `::/128`                                                                | 未指定地址和本网地址                                 |
-| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                      | RFC1918 私有网络                                    |
-| `169.254.0.0/16`, `fe80::/10`                                                        | 链路本地地址和常见云元数据路径                       |
-| `169.254.169.254`, `metadata.google.internal`                                        | 云元数据服务                                         |
-| `100.64.0.0/10`                                                                      | 运营商级 NAT 共享地址空间                           |
-| `198.18.0.0/15`, `2001:2::/48`                                                       | 基准测试范围                                         |
-| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档范围                                   |
-| `224.0.0.0/4`, `ff00::/8`                                                            | 多播                                                 |
-| `240.0.0.0/4`                                                                        | 保留 IPv4                                           |
-| `fc00::/7`, `fec0::/10`                                                              | IPv6 本地/私有范围                                  |
-| `100::/64`, `2001:20::/28`                                                           | IPv6 丢弃和 ORCHIDv2 范围                           |
-| `64:ff9b::/96`, `64:ff9b:1::/48`                                                     | 带嵌入式 IPv4 的 NAT64 前缀                         |
-| `2002::/16`, `2001::/32`                                                             | 带嵌入式 IPv4 的 6to4 和 Teredo                     |
-| `::/96`, `::ffff:0:0/96`                                                             | IPv4 兼容和 IPv4 映射的 IPv6                        |
+| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                  | IPv4 环回                                        |
+| `::1/128`                                                                            | IPv6 环回                                        |
+| `0.0.0.0/8`, `::/128`                                                                | 未指定地址和本网络地址               |
+| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                      | RFC1918 私有网络                             |
+| `169.254.0.0/16`, `fe80::/10`                                                        | 链路本地地址和常见云元数据路径 |
+| `169.254.169.254`, `metadata.google.internal`                                        | 云元数据服务                              |
+| `100.64.0.0/10`                                                                      | 运营商级 NAT 共享地址空间               |
+| `198.18.0.0/15`, `2001:2::/48`                                                       | 基准测试范围                                  |
+| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档范围                 |
+| `224.0.0.0/4`, `ff00::/8`                                                            | 多播                                            |
+| `240.0.0.0/4`                                                                        | 保留 IPv4                                        |
+| `fc00::/7`, `fec0::/10`                                                              | IPv6 本地/私有范围                            |
+| `100::/64`, `2001:20::/28`                                                           | IPv6 丢弃和 ORCHIDv2 范围                     |
+| `64:ff9b::/96`, `64:ff9b:1::/48`                                                     | 带嵌入式 IPv4 的 NAT64 前缀                    |
+| `2002::/16`, `2001::/32`                                                             | 带嵌入式 IPv4 的 6to4 和 Teredo                   |
+| `::/96`, `::ffff:0:0/96`                                                             | IPv4 兼容和 IPv4 映射的 IPv6                 |

-如果你的云提供商或网络平台记录了其他元数据主机或保留范围，也请将它们加入。
+如果你的云提供商或网络平台记录了额外的元数据主机或保留范围，也请将它们加入。

 ## 验证

-从运行 OpenClaw 的同一主机、容器或服务账户验证代理：
+从运行 OpenClaw 的同一主机、容器或服务账号验证代理：

 ```bash
 openclaw proxy validate --proxy-url http://127.0.0.1:3128
 ```

-默认情况下，如果未提供自定义目标，该命令会检查 `https://example.com/` 是否成功，并启动一个临时 loopback 金丝雀，代理不得访问它。当代理返回非 2xx 拒绝响应，或通过传输失败阻止该金丝雀时，默认拒绝检查通过；如果成功响应到达金丝雀，则检查失败。如果未启用并配置代理，验证会报告配置问题；在更改配置前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试部署特定预期。自定义被拒绝目标采用故障关闭：任何 HTTP 响应都表示该目标可通过代理访问，任何传输错误都会被报告为不确定，因为 OpenClaw 无法证明代理阻止了一个可访问来源。验证失败时，该命令以代码 1 退出。
+默认情况下，如果没有提供自定义目标，该命令会检查 `https://example.com/` 是否成功，并启动一个临时环回 canary，代理不得访问该 canary。当代理返回非 2xx 拒绝响应，或以传输失败阻止 canary 时，默认拒绝检查通过；如果成功响应到达 canary，则检查失败。如果未启用并配置代理，验证会报告配置问题；在更改配置前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试部署特定预期。添加 `--apns-reachable` 还可验证直接 APNs HTTP/2 递送是否能够通过代理打开 CONNECT 隧道并收到沙箱 APNs 响应；该探测使用故意无效的提供商令牌，因此预期结果为 `403 InvalidProviderToken`，并会计为可达。自定义拒绝目标采用故障关闭：任何 HTTP 响应都表示目标可通过代理访问，而任何传输错误都会报告为无法判定，因为 OpenClaw 无法证明代理阻止了一个可达来源。验证失败时，该命令以代码 1 退出。

-使用 `--json` 进行自动化。JSON 输出包含总体结果、有效代理配置来源、任何配置错误，以及每个目标检查。代理 URL 凭据会在文本和 JSON 输出中被遮蔽：
+使用 `--json` 进行自动化。JSON 输出包含总体结果、有效代理配置来源、任何配置错误，以及每个目标检查。代理 URL 凭据会在文本和 JSON 输出中被遮盖：

 ```json
 {
@ -165,12 +165,18 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128
      "url": "https://example.com/",
      "ok": true,
      "status": 200
+    },
+    {
+      "kind": "apns",
+      "url": "https://api.sandbox.push.apple.com",
+      "ok": true,
+      "status": 403
    }
  ]
 }
 ```

-你也可以用 `curl` 手动验证：
+你也可以使用 `curl` 手动验证：

 ```bash
 curl -x http://127.0.0.1:3128 https://example.com/
@ -178,7 +184,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
 curl -x http://127.0.0.1:3128 http://169.254.169.254/
 ```

-公共请求应该成功。环回和元数据请求应该被代理阻止。对于 `openclaw proxy validate`，内置的环回金丝雀可以区分代理拒绝和可访问的源站。自定义 `--denied-url` 检查没有这个金丝雀，因此除非你的代理公开了可单独验证的部署专用拒绝信号，否则应将 HTTP 响应和含糊的传输失败都视为验证失败。
+公共请求应成功。回环和元数据请求应被代理阻止。对于 `openclaw proxy validate`，内置回环探针可以区分代理拒绝和可达源站。自定义 `--denied-url` 检查没有该探针，因此除非你的代理公开了可单独验证的部署特定拒绝信号，否则应将 HTTP 响应和含糊的传输失败都视为验证失败。

 然后启用 OpenClaw 代理路由：

@ -198,11 +204,11 @@ proxy:

 ## 限制

- 代理可提升对进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级网络沙箱。
- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及子进程可能会绕过 Node 级代理路由，除非它们继承并遵循代理环境变量。
- IRC 是一个原始 TCP/TLS 渠道，不在操作员管理的前向代理路由范围内。在要求所有出站流量都通过该前向代理的部署中，除非已明确批准直接 IRC 出站，否则请设置 `channels.irc.enabled=false`。
- 本地调试代理是诊断工具；在托管代理模式处于活动状态时，它对代理请求和 CONNECT 隧道的直接上游转发默认处于禁用状态；仅为已批准的本地诊断启用直接转发。
- 需要时，应在操作员代理策略中将用户本地 WebUI 和本地模型服务器加入允许名单；OpenClaw 不会为它们公开通用的本地网络绕过机制。
- Gateway 网关控制平面代理绕过有意限制为 `localhost` 和字面量环回 IP URL。对于本地直接 Gateway 网关控制平面连接，请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主机名会像普通基于主机名的流量一样路由。
+- 该代理改善了进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是 OS 级网络沙箱。
+- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及子进程可能绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。
+- IRC 是一个原始 TCP/TLS 渠道，位于操作员管理的正向代理路由之外。在要求所有出站流量都经过该正向代理的部署中，除非已明确批准直接 IRC 出站流量，否则请设置 `channels.irc.enabled=false`。
+- 本地调试代理是诊断工具；在托管代理模式处于活动状态时，默认禁用其对代理请求和 CONNECT 隧道的直接上游转发；仅为已批准的本地诊断启用直接转发。
+- 需要时，应在操作员代理策略中允许用户本地 WebUI 和本地模型服务器；OpenClaw 不会为它们公开通用的本地网络绕过机制。
+- Gateway 网关控制平面的代理绕过有意限制为 `localhost` 和字面量回环 IP URL。请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789` 进行本地直连 Gateway 网关控制平面连接；其他主机名会像普通基于主机名的流量一样路由。
 - OpenClaw 不会检查、测试或认证你的代理策略。
- 将代理策略变更视为安全敏感的运维变更。
+- 将代理策略更改视为安全敏感的运维更改。