跳转至

openclaw proxy

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

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 [--json]
openclaw proxy sessions [--limit <count>] [--json]
openclaw proxy query --preset <name> [--session <id>] [--json]
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 覆盖或添加，可重复）
  • 一个针对临时回环 canary 的 拒绝 检查（可使用 --denied-url 覆盖，可重复）

自定义 --denied-url 目标采用 fail-closed（失败即关闭）语义：所有 HTTP 响应以及模糊的传输失败均计为失败，除非你能独立验证部署特定的拒绝信号。内置回环 canary 是唯一将传输错误视为已阻断证明的目标。

添加 --apns-reachable 还可通过代理打开 APNs HTTP/2 CONNECT 隧道，并确认沙盒 APNs 有响应。该探测会发送一个故意无效的 provider 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 同时验证沙盒 APNs HTTP/2 可通过代理访问
--apns-authority <url> 要探测的 APNs 权威端点（默认 https://api.sandbox.push.apple.com；生产环境为 https://api.push.apple.com）
--timeout-ms <ms> 单次请求超时时间

当代理配置或目标检查失败时，以退出码 1 退出。

部署指导和拒绝语义请参阅 网络代理。

调试代理

start 启动本地捕获代理，并输出其 URL、CA 证书路径和捕获数据库路径。按 Ctrl+C 停止。默认绑定 127.0.0.1，除非设置了 --host。

run 启动本地调试代理，然后在已应用代理环境变量的情况下运行 <cmd...>（位于 -- 之后），并将其置于独立的捕获会话中。

捕获持久化使用异步 worker 操作。在有序关闭时，start 和 run 会等待已受理的捕获写入和会话清理完成。即使原始 HTTP 响应已送达调用方，清理期间的捕获失败仍可上报。

使用 proxy capture SDK 的集成必须等待捕获最终化，并释放其异步存储租约。直接关闭数据库维护会使捕获受理失效，且不能替代上述清理；同步终结器无法排空异步捕获工作。

调试代理的直接上游转发会为诊断打开上游套接字。当 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

coverage、sessions 和 query 默认已返回 JSON。它们也接受 --json 作为显式机器输出写法，以便脚本保持一致。在该模式下，coverage 保留其报告对象，而 sessions 和 query 分别将它们的行包装在 sessions 和 rows 下。

blob --id <blobId> 打印已捕获负载 blob 的原始内容。

purge 删除所有已捕获的流量元数据和 blob。捕获内容属于本地调试数据。完成后请清除它们。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw