OpenClaw Proxy CLI: Validate and Debug Traffic
Reference for the openclaw proxy command, covering operator-managed proxy validation and the local debug proxy capture inspector. For operators and developers debugging transport-level routing.
Read this when
- You need to validate operator-managed proxy routing before deployment
- You need to capture OpenClaw transport traffic locally for debugging
- You want to inspect debug proxy sessions, blobs, or built-in query presets
openclaw proxy
Validate proxy routing managed by operators, or spin up the local explicit debug proxy and review the traffic it captures.
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 checks an operator-managed forward proxy ahead of time. The remaining commands support transport-level debugging: start a local capturing proxy, execute a child command through it, list capture sessions, inspect traffic patterns, read captured blobs, and clear local capture data.
Validate
Determines the effective operator-managed proxy URL from --proxy-url, configuration (proxy.proxyUrl), or OPENCLAW_PROXY_URL, with that order of precedence. If no proxy is enabled and configured, it reports a configuration issue; use --proxy-url to run a one-off preflight without modifying config.
Managed proxy URLs rely on http:// for a standard forward-proxy listener, or https:// when OpenClaw must establish TLS to the proxy endpoint before sending proxy requests. To trust a private CA for that TLS connection, use --proxy-ca-file.
By default, it executes:
- one allowed check against
https://example.com/(override or add with--allowed-url, repeatable) - one denied check against a temporary loopback canary (override with
--denied-url, repeatable)
Custom --denied-url targets are fail-closed: both HTTP responses and ambiguous transport failures count as failures unless you can independently verify a deployment-specific denial signal. The built-in loopback canary is the only target where a transport error is treated as proof of blocking.
Add --apns-reachable to also open an APNs HTTP/2 CONNECT tunnel through the proxy and confirm sandbox APNs responds. The probe sends an intentionally invalid provider token, so an APNs 403 InvalidProviderToken response counts as a successful reachability signal (not a failure).
Options
| Flag | Effect |
|---|---|
--json | print machine-readable JSON |
--proxy-url <url> | validate this http:///https:// proxy URL instead of config or env |
--proxy-ca-file <path> | trust this PEM CA file for TLS verification of an HTTPS proxy endpoint |
--allowed-url <url> | destination expected to succeed through the proxy (repeatable) |
--denied-url <url> | destination expected to be blocked by the proxy (repeatable) |
--apns-reachable | also verify sandbox APNs HTTP/2 is reachable through the proxy |
--apns-authority <url> | APNs authority to probe (default https://api.sandbox.push.apple.com; production is https://api.push.apple.com) |
--timeout-ms <ms> | per-request timeout |
Exits with code 1 when proxy config or destination checks fail.
See Network Proxy for deployment guidance and denial semantics.
Debug proxy
start launches a local capturing proxy and prints its URL, CA cert path, and capture DB path; stop with Ctrl+C. Defaults to binding 127.0.0.1 unless --host is set.
run starts a local debug proxy, then runs <cmd...> (after --) with the proxy env applied, under its own capture session.
The debug proxy's direct upstream forwarding opens upstream sockets for diagnostics. When OpenClaw managed proxy mode is active, direct forwarding for proxy requests and CONNECT tunnels is disabled by default; set OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1 only for approved local diagnostics.
coverage prints a JSON report (summary + per-transport entries) of which transports are captured, proxy-only, or uncovered.
sessions lists recent capture sessions (--limit, default 20).
query --preset <name> runs a built-in query against captured traffic, optionally scoped to --session <id>. Presets:
double-sendsretry-stormscache-bustingws-duplicate-framesmissing-ackerror-bursts
coverage, sessions, and query already output JSON by default. For scripts that need consistent formatting, they also support --json as an explicit machine-readable option. In this mode, coverage retains its report object, whereas sessions and query place their rows under sessions and rows, respectively.
The raw content of a captured payload blob is printed by blob --id <blobId>.
All stored traffic metadata and blobs are removed by purge. Since captures serve as local debugging data, clean them up once you are done.