跳转至

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,以及清除本地捕获数据。

验证

按此优先级顺序检查生效的操作员管理代理 URL:--proxy-url、配置(proxy.proxyUrl)或 OPENCLAW_PROXY_URL。如果代理未启用且未配置,则报告配置问题。传入 --proxy-url 以进行一次性预检,而不修改配置。

受管代理 URL 使用 http:// 表示普通正向代理监听器,或使用 https:// 表示 OpenClaw 在发送代理请求之前必须先与代理端点本身建立 TLS。使用 --proxy-ca-file 为该 TLS 连接信任私有 CA。

默认会执行:

  • 对 https://example.com/ 执行一次 允许 检查(可通过 --allowed-url 覆盖/添加,可重复)
  • 对临时回环金丝雀执行一次 拒绝 检查(可通过 --denied-url 覆盖,可重复)

自定义 --denied-url 目标采用失败关闭策略:HTTP 响应和模糊的传输失败都计为失败,除非你能独立验证部署特定的拒绝信号。内置回环金丝雀是唯一将传输错误视为阻断证据的目标。

添加 --apns-reachable 以同时通过代理打开 APNs HTTP/2 CONNECT 隧道,并确认沙箱 APNs 有响应。该检查会故意发送无效的 provider token,因此 APNs 的 403 InvalidProviderToken 响应被视为成功的可达性信号(而非失败)。

选项

Flag Effect
--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 authority(默认 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...>。OpenClaw 子进程会通过其调试端点 URL 中一个临时的、与会话绑定的捕获 token,将插桩的 HTTPS 和 WebSocket 负载转发给父进程。常规 HTTP 代理变量和已存储的捕获 URL 保持无凭据。父进程仍然是唯一的持久化客户端;子进程不会打开捕获数据库。私有捕获端点不能读取或清除捕获,并随代理关闭。对于会修改其他 OpenClaw 状态的子命令,请先运行 Gateway,以便这些命令可以路由其写入。离线捕获在子进程退出前保持父进程独占所有权。

捕获持久化使用异步 worker 操作。当本地 Gateway 拥有状态目录时,CLI 会将代理监听器和子命令保留在本地,并通过该 Gateway 路由捕获读取和写入。当 Gateway 停止时,CLI 通过捕获清理保持独占的离线所有权。失败或不确定的 Gateway 请求绝不会在本地重放。没有捕获路由的旧版 Gateway 需要在离线捕获之前进行更新或有序停止。在有序关闭时, 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