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-sendsretry-stormscache-bustingws-duplicate-framesmissing-ackerror-bursts
coverage、sessions 和 query 默认已返回 JSON。它们也接受 --json 作为显式的机器输出形式,以便脚本保持一致。
在该模式下,coverage 保留其报告对象,而 sessions 和 query
分别将它们的行包装在 sessions 和 rows 下。
blob --id <blobId> 打印捕获的负载 blob 的原始内容。
purge 删除所有捕获的流量元数据和 blob。捕获数据是本地调试数据。完成后请清除它们。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw