4ea0556f64
Adds `openclaw proxy validate` for operator-managed proxy preflight checks, including allowed/denied destination validation, CLI output, tests, docs, and changelog coverage. Maintainer follow-ups before landing: - validate custom allowed URLs before probing; - use a temporary loopback canary for default denied checks and fail custom denied transport errors as unverifiable; - redact proxy URL userinfo, query strings, and fragments from text/JSON validation output. Validation: - `pnpm test src/infra/net/proxy/proxy-validation.test.ts src/cli/proxy-cli.runtime.test.ts src/cli/proxy-cli.test.ts -- --reporter=verbose` - `pnpm exec oxfmt --check --threads=1 CHANGELOG.md src/cli/proxy-cli.ts src/cli/proxy-cli.runtime.ts src/cli/proxy-cli.test.ts src/cli/proxy-cli.runtime.test.ts src/infra/net/proxy/proxy-validation.ts src/infra/net/proxy/proxy-validation.test.ts docs/cli/proxy.md docs/security/network-proxy.md` - `pnpm exec oxlint src/cli/proxy-cli.runtime.ts src/cli/proxy-cli.runtime.test.ts` - `git diff --check` - Testbox `pnpm install && OPENCLAW_TESTBOX=1 pnpm check:changed` on `tbx_01kqgz68ff20n3dtrgq0j1mykt` - GitHub CI success on `321b3aaf2b8be27dec6ce2ac5e4007ed064218b5`
2.9 KiB
summary, read_when, title
| summary | read_when | title | |||
|---|---|---|---|---|---|
| CLI reference for `openclaw proxy`, including operator-managed proxy validation and the local debug proxy capture inspector |
|
Proxy |
openclaw proxy
Validate operator-managed proxy routing, or run the local explicit debug proxy and inspect captured traffic.
Use validate to preflight an operator-managed forward proxy before enabling
OpenClaw proxy routing. The other commands are debugging tools for
transport-level investigation: they can start a local proxy, run a child command
with capture enabled, list capture sessions, query common traffic patterns, read
captured blobs, and purge local capture data.
Commands
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <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 checks the effective operator-managed proxy URL from
--proxy-url, config, or OPENCLAW_PROXY_URL. It reports a config problem when
no proxy is enabled and configured; use --proxy-url for a one-off preflight
before changing config. By default it verifies that a public destination succeeds
through the proxy and that the proxy cannot reach a temporary loopback canary.
Custom denied destinations are fail-closed: HTTP responses and ambiguous
transport failures both fail unless you can verify a deployment-specific denial
signal separately.
Options:
--json: print machine-readable JSON.--proxy-url <url>: validate this proxy URL instead of config or env.--allowed-url <url>: add a destination expected to succeed through the proxy. Repeat to check multiple destinations.--denied-url <url>: add a destination expected to be blocked by the proxy. Repeat to check multiple destinations.--timeout-ms <ms>: per-request timeout in milliseconds.
See Network Proxy for deployment guidance and denial semantics.
Query presets
openclaw proxy query --preset <name> accepts:
double-sendsretry-stormscache-bustingws-duplicate-framesmissing-ackerror-bursts
Notes
startdefaults to127.0.0.1unless--hostis set.runstarts a local debug proxy and then runs the command after--.validateexits with code 1 when proxy config or destination checks fail.- Captures are local debugging data; use
openclaw proxy purgewhen finished.