mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 08:40:44 +00:00
d5b0083300
Summary: - This PR routes direct APNs HTTP/2 sends through an APNs allowlisted managed-proxy CONNECT wrapper, adds APNs proxy validation/docs/guardrails, and expands regression and live-test coverage. - Reproducibility: yes. source-reproducible: current main `sendApnsRequest()` still uses raw `http2.connect(au ... nly covers HTTP/global-agent/Undici hooks. I did not run a live APNs reproduction in this read-only review. Automerge notes: - PR branch already contained follow-up commit before automerge: test: guard raw HTTP2 APNs connections - PR branch already contained follow-up commit before automerge: test: guard raw HTTP2 with OpenGrep - PR branch already contained follow-up commit before automerge: lint: ban raw HTTP2 imports - PR branch already contained follow-up commit before automerge: fix: use managed proxy state for APNs - PR branch already contained follow-up commit before automerge: test: exercise APNs active proxy state - PR branch already contained follow-up commit before automerge: fix: reject conflicting managed proxy activation Validation: - ClawSweeper review passed for headdab7c86a75. - Required merge gates passed before the squash merge. Prepared head SHA:dab7c86a75Review: https://github.com/openclaw/openclaw/pull/74905#issuecomment-4350181159 Co-authored-by: jesse-merhi <79823012+jesse-merhi@users.noreply.github.com> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>
85 lines
3.8 KiB
Markdown
85 lines
3.8 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>] [--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` 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. Add `--apns-reachable` to also open an APNs HTTP/2 CONNECT
|
|
tunnel through the proxy and confirm sandbox APNs responds; the probe uses an
|
|
intentionally invalid provider token, so an APNs `403 InvalidProviderToken`
|
|
response is a successful reachability signal.
|
|
|
|
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.
|
|
- `--apns-reachable`: also verify sandbox APNs HTTP/2 is reachable through the proxy.
|
|
- `--apns-authority <url>`: APNs authority to probe with `--apns-reachable` (`https://api.sandbox.push.apple.com` by default; production is `https://api.push.apple.com`).
|
|
- `--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 `--`.
|
|
- 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.
|
|
- `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)
|