> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy

# `openclaw proxy`

驗證由操作員管理的代理路由，或執行本機明確偵錯代理並檢查擷取的流量。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw proxy validate [--json] [--proxy-url <url>] [--proxy-ca-file <path>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
openclaw proxy blob --id <blobId>
openclaw proxy purge
```

`validate` 會預先檢查由操作員管理的正向代理。其餘都是用於傳輸層級調查的偵錯工具：啟動本機擷取代理、透過它執行子命令、列出擷取工作階段、查詢流量模式、讀取擷取的 blob，以及清除本機擷取資料。

## 驗證

依序從 `--proxy-url`、設定 (`proxy.proxyUrl`) 或 `OPENCLAW_PROXY_URL` 檢查有效的由操作員管理代理 URL。若未啟用並設定代理，會回報設定問題；傳入 `--proxy-url` 可在不修改設定的情況下執行一次性預先檢查。

受管理的代理 URL 會使用 `http://` 表示純正向代理監聽器；當 OpenClaw 必須先對代理端點本身開啟 TLS，再傳送代理請求時，則使用 `https://`。使用 `--proxy-ca-file` 信任該 TLS 連線的私有 CA。

預設會執行：

* 一項針對 `https://example.com/` 的**允許**檢查（可用 `--allowed-url` 覆寫/新增，可重複）
* 一項針對臨時 loopback canary 的**拒絕**檢查（可用 `--denied-url` 覆寫，可重複）

自訂 `--denied-url` 目標採用失敗即關閉：除非你能獨立驗證特定部署的拒絕訊號，否則 HTTP 回應和模稜兩可的傳輸失敗都會計為失敗。內建 loopback canary 是唯一會將傳輸錯誤視為封鎖證明的目標。

加入 `--apns-reachable` 也會透過代理開啟 APNs HTTP/2 CONNECT 通道，並確認 sandbox APNs 會回應。探測會傳送刻意無效的提供者 token，因此 APNs `403 InvalidProviderToken` 回應會計為成功的可達性訊號（不是失敗）。

### 選項

| 旗標                       | 效果                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `--json`                 | 列印機器可讀的 JSON                                                                                           |
| `--proxy-url <url>`      | 驗證這個 `http://`/`https://` 代理 URL，而非設定或環境變數                                                             |
| `--proxy-ca-file <path>` | 信任此 PEM CA 檔案，用於 HTTPS 代理端點的 TLS 驗證                                                                    |
| `--allowed-url <url>`    | 預期可透過代理成功連線的目的地（可重複）                                                                                   |
| `--denied-url <url>`     | 預期會被代理封鎖的目的地（可重複）                                                                                      |
| `--apns-reachable`       | 同時驗證 sandbox APNs HTTP/2 可透過代理到達                                                                       |
| `--apns-authority <url>` | 要探測的 APNs authority（預設 `https://api.sandbox.push.apple.com`；production 是 `https://api.push.apple.com`） |
| `--timeout-ms <ms>`      | 每個請求的逾時時間                                                                                              |

當代理設定或目的地檢查失敗時，會以代碼 1 結束。

部署指引與拒絕語意請參閱[網路代理](/zh-TW/security/network-proxy)。

## 偵錯代理

`start` 會啟動本機擷取代理，並列印其 URL、CA 憑證路徑和擷取 DB 路徑；使用 Ctrl+C 停止。除非設定 `--host`，否則預設繫結到 `127.0.0.1`。

`run` 會啟動本機偵錯代理，然後在套用代理環境的情況下，於其自己的擷取工作階段中執行 `<cmd...>`（在 `--` 之後）。

偵錯代理的直接上游轉送會為診斷開啟上游 socket。當 OpenClaw 受管理代理模式啟用時，代理請求和 CONNECT 通道的直接轉送預設會停用；僅可針對已核准的本機診斷設定 `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1`。

`coverage` 會列印 JSON 報告（`summary` + 每個傳輸的 `entries`），說明哪些傳輸會被擷取、僅限代理，或未涵蓋。

`sessions` 會列出最近的擷取工作階段（`--limit`，預設 20）。

`query --preset <name>` 會對擷取的流量執行內建查詢，並可選擇以 `--session <id>` 限定範圍。預設集：

* `double-sends`
* `retry-storms`
* `cache-busting`
* `ws-duplicate-frames`
* `missing-ack`
* `error-bursts`

`blob --id <blobId>` 會列印擷取的 payload blob 原始內容。

`purge` 會刪除所有擷取的流量中繼資料和 blob。擷取內容是本機偵錯資料；完成後請清除。

## 相關

* [命令列介面參考](/zh-TW/cli)
* [網路代理](/zh-TW/security/network-proxy)
* [受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)