openclaw proxy 提供两组功能：运营商代理路由验证（validate）和本地调试代理流量捕获。validate 可预检 http:// 或 https:// 代理，支持 --apns-reachable 检查 APNs 连通性，失败时退出码为 1。调试命令 start/run 启动本地代理，query 使用预设（如 double-sends）分析捕获数据，结束后用 purge 清理。

OpenClaw proxy 代理验证与调试命令参考

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

使用 validate 在启用 OpenClaw 代理路由之前对运营商管理的正向代理进行预检查。其余命令是用于传输层排查的调试工具：它们可以启动本地代理、运行带有捕获功能的子命令、列出捕获会话、查询常见流量模式、读取捕获的 blob，以及清除本地捕获数据。

命令

openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
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 coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
openclaw proxy blob --id <blobId>
openclaw proxy purge

Validate

openclaw proxy validate 检查生效的运营商管理代理 URL，来源依次为 --proxy-url、配置文件或环境变量 OPENCLAW_PROXY_URL。管理代理 URL 可使用 http:// 表示普通正向代理监听器，或 https:// 表示 OpenClaw 必须先向代理端点建立 TLS 连接再发送代理请求。当未启用或未配置代理时，会报告配置问题；在修改配置前可用 --proxy-url 进行一次性预检查。添加 --proxy-ca-file 可信任 HTTPS 代理端点 TLS 连接所用的私有 CA。默认行为是：验证通过代理能否成功访问一个公共目标，以及代理能否访问一个临时回环 canary（预期被拒绝）。自定义被拒绝的目标采用“失败阻断”逻辑：若代理返回 HTTP 响应或发生不明传输故障，均视为失败，除非你能单独验证部署特定的拒绝信号。添加 --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>：添加一个预期可通过代理成功访问的目标 URL。可重复使用以检查多个目标。
• --denied-url <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>：每个请求的超时时间（毫秒）。

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

查询预设

openclaw proxy query --preset <name> 接受的预设名称：

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

说明

• start 默认绑定到 127.0.0.1，除非设置了 --host。
• run 先启动本地调试代理，然后执行 -- 之后的命令。
• 调试代理的直接上游转发会为诊断而打开上游 socket。当启用 OpenClaw 管理代理模式时，默认情况下会禁用代理请求和 CONNECT 隧道的直接转发；仅在经过批准的本地诊断中设置 OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1。
• validate 在代理配置或目标检查失败时以退出码 1 结束。
• 捕获数据属于本地调试数据，使用 openclaw proxy purge 清理。

相关文档

• CLI 参考
• 网络代理
• 受信任代理认证

常见问题

怎么用 openclaw proxy validate 检查代理是否可用？

直接运行 openclaw proxy validate，它会根据配置文件或 OPENCLAWS_PROXY_URL 检查代理。若要手动指定，使用 --proxy-url http://your-proxy:8080。加上 --json 可输出机器可读结果。若返回退出码 1 表示检查失败。

openclaw proxy query 预设有哪些？怎么用？

预设包括 double-sends、retry-storms、cache-busting、ws-duplicate-frames、missing-ack、error-bursts。用法示例：openclaw proxy query --preset double-sends --session <sessionId> 会分析指定会话中的重复发送模式。

调试代理捕获的数据怎么清理？

运行 openclaw proxy purge 即可清除所有本地捕获的会话数据。建议在完成调试后执行一次，避免占用磁盘空间。