vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 10:30:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add proxy validation command

Browse Source 
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`
This commit is contained in:
Jesse Merhi
2026-05-01 15:19:55 +10:00
committed by GitHub
parent 214b3d3336
commit 4ea0556f64
9 changed files with 1428 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/cli/proxy.md
View File

@@ -1,6 +1,7 @@
---
summary: "CLI reference for `openclaw proxy`, the local debug proxy and capture inspector"
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"
@@ -8,18 +9,21 @@ title: "Proxy"
# `openclaw proxy`
Run the local explicit debug proxy and inspect captured traffic.
Validate operator-managed proxy routing, or run the local explicit debug proxy
and inspect captured traffic.
This is a debugging command for transport-level investigation. It 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.
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>]
@@ -27,6 +31,28 @@ 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:
@@ -42,9 +68,11 @@ openclaw proxy purge
- `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)

32
docs/security/network-proxy.md
View File

@@ -135,13 +135,43 @@ If your cloud provider or network platform documents additional metadata hosts o
Validate the proxy from the same host, container, or service account that runs OpenClaw:
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
By default, when no custom destinations are provided, the command checks that `https://example.com/` succeeds and starts a temporary loopback canary that the proxy must not reach. The default denied check passes when the proxy returns a non-2xx denial response or blocks the canary with a transport failure; it fails if a successful response reaches the canary. If no proxy is enabled and configured, validation reports a config problem; use `--proxy-url` for a one-off preflight before changing config. Use `--allowed-url` and `--denied-url` to test deployment-specific expectations. Custom denied destinations are fail-closed: any HTTP response means the destination was reachable through the proxy, and any transport error is reported as inconclusive because OpenClaw cannot prove the proxy blocked a reachable origin. On validation failure, the command exits with code 1.
Use `--json` for automation. The JSON output contains the overall result, the effective proxy config source, any config errors, and each destination check. Proxy URL credentials are redacted in text and JSON output:
```json
{
"ok": true,
"config": {
"enabled": true,
"proxyUrl": "http://127.0.0.1:3128/",
"source": "override",
"errors": []
},
"checks": [
{
"kind": "allowed",
"url": "https://example.com/",
"ok": true,
"status": 200
}
]
}
```
You can also validate manually with `curl`:
```bash
curl -x http://127.0.0.1:3128 https://example.com/
curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
The public request should succeed. The loopback and metadata requests should fail at the proxy.
The public request should succeed. The loopback and metadata requests should be blocked by the proxy. For `openclaw proxy validate`, the built-in loopback canary can distinguish a proxy denial from a reachable origin. Custom `--denied-url` checks do not have that canary, so treat both HTTP responses and ambiguous transport failures as validation failures unless your proxy exposes a deployment-specific denial signal you can verify separately.
Then enable OpenClaw proxy routing: