mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-02 06:27:29 +02:00
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`
79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw proxy`, including operator-managed proxy validation and the local debug proxy capture inspector"
|
|
read_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
|
|
title: "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
|
|
|
|
```bash
|
|
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](/security/network-proxy) for deployment guidance and denial
|
|
semantics.
|
|
|
|
## Query presets
|
|
|
|
`openclaw proxy query --preset <name>` accepts:
|
|
|
|
- `double-sends`
|
|
- `retry-storms`
|
|
- `cache-busting`
|
|
- `ws-duplicate-frames`
|
|
- `missing-ack`
|
|
- `error-bursts`
|
|
|
|
## Notes
|
|
|
|
- `start` defaults to `127.0.0.1` unless `--host` is set.
|
|
- `run` starts a local debug proxy and then runs the command after `--`.
|
|
- `validate` exits with code 1 when proxy config or destination checks fail.
|
|
- Captures are local debugging data; use `openclaw proxy purge` when finished.
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|
|
- [Network Proxy](/security/network-proxy)
|
|
- [Trusted proxy auth](/gateway/trusted-proxy-auth)
|