Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.codezero.io/llms.txt

Use this file to discover all available pages before exploring further.

Cordon integrates with OpenClaw so the gateway and any agent it spawns can reach LLM providers, web fetch APIs, and web search providers through cordon — with credentials injected at the network layer instead of stored in OpenClaw’s config.

​
Scope

OpenClaw setup treats the default ~/.openclaw/ profile as its own cordon project. It stores config at ~/.openclaw/cordon.toml, updates ~/.openclaw/openclaw.json, and configures the user-level launchd/systemd daemon (ai.openclaw.gateway) to trust cordon’s CA. This keeps OpenClaw isolated from unrelated repository configs while still serving projects through one gateway. OpenClaw does not expose --scope, and setup rejects the generic user-scope config at ~/.config/cordon/cordon.toml. If you need follow-up commands such as cordon route, cordon start, cordon env, or cordon service, pass --config ~/.openclaw/cordon.toml. Automated setup only supports the default profile in v1; OPENCLAW_CONFIG_PATH and OPENCLAW_STATE_DIR must be unset or point at the default ~/.openclaw locations. See Scopes for path details and trade-offs.

​
Automated setup

The fastest way to get started: 
cordon setup openclaw
This:
  1. Detects the openclaw CLI on PATH (fails fast with a clear message if missing, before touching any cordon-side state)
  2. Generates CA certificates (if not already present)
  3. Creates a scaffold ~/.openclaw/cordon.toml
  4. Writes proxy.enabled=true and the authenticated proxy.proxyUrl directly to ~/.openclaw/openclaw.json
  5. Reinstalls the OpenClaw daemon (openclaw daemon uninstall && openclaw daemon install) with NODE_EXTRA_CA_CERTS and NODE_USE_SYSTEM_CA=1 layered into the install-time env
  6. Restarts the daemon so the new proxy config takes effect
  7. Probes the daemon with openclaw daemon status as a smoke test
  8. Installs a cordon agent skill to ~/.openclaw/skills/cordon/SKILL.md
The daemon reinstall is the disruptive step — the OpenClaw gateway is stopped and restarted as part of setup. Active sessions are interrupted. To run cordon as a background service, run cordon service install --config ~/.openclaw/cordon.toml after setup.

​
Remove the setup

cordon integration disable openclaw
Teardown is intentionally best-effort: partial failures (daemon already stopped, skill file already gone) print warnings but don’t abort scripted cleanup chains. The teardown reinstalls the OpenClaw daemon with cordon’s CA env vars explicitly stripped from the install subprocess, so even users who have eval $(cordon env) exported in their shell get a fully cordon-free service definition.

​
Adding routes

After setup, add a route for your LLM provider with cordon route add --config ~/.openclaw/cordon.toml and, if using the keyring secret source, store the credential with cordon secret set. Pass --config ~/.openclaw/cordon.toml to cordon route, cordon start, and cordon service commands so they target the OpenClaw config.
Anthropic uses type: header with header_name: x-api-key and no scheme. Using an Authorization header will result in 401 errors.

​
Provider auto-detection

OpenClaw inspects env.vars in ~/.openclaw/openclaw.json (or the per-provider auth profile) to decide which LLM provider to use. Since cordon injects the real API key at the network layer, OpenClaw still needs a value present to select the right provider. A dummy is fine: 
{
  "env": {
    "vars": {
      "ANTHROPIC_API_KEY": "dummy-replaced-by-cordon"
    }
  }
}
Without a value, OpenClaw will fail to select the provider even though cordon has the real credential ready to inject. (If you previously had a real key in env.vars, replace it — leaving it there isn’t unsafe, but it defeats the point of cordon.)

​
Manual setup

Prefer cordon setup openclaw for the default OpenClaw profile. It writes ~/.openclaw/openclaw.json directly, then runs the daemon reinstall, restart, and smoke test in the required order. If setup cannot cover your environment, the equivalent by hand is: 
# 1. Get cordon's env (only NODE_EXTRA_CA_CERTS survives OpenClaw's service-env filter)
eval "$(cordon env --config ~/.openclaw/cordon.toml)"

# 2. Reinstall the daemon so the launchd/systemd service env is regenerated
openclaw daemon uninstall && openclaw daemon install

# 3. Activate the managed proxy in ~/.openclaw/openclaw.json
#    Set proxy.enabled=true and proxy.proxyUrl="$HTTPS_PROXY".

# 4. Restart for the proxy config to take effect
openclaw daemon restart
The proxy.proxyUrl must use http: — OpenClaw’s isSupportedProxyUrl rejects https:. Cordon’s proxy listener is plain HTTP (loopback only), which matches.

​
How it works

OpenClaw’s gateway is a Node.js process. When proxy.enabled=true is set, its startProxy() lifecycle installs a global undici dispatcher routing all outbound HTTP through proxy.proxyUrl, and sets OPENCLAW_PROXY_ACTIVE=1 on the process. This covers:
  • LLM provider API calls (Anthropic, OpenRouter, etc.) — gateway-side fetch traffic
  • web_fetch tool calls — strict-mode fetch takes the canUseManagedProxy branch
  • web_search tool calls — explicitly uses the trusted-env-proxy fetch wrapper
The NODE_EXTRA_CA_CERTS env var lives in OpenClaw’s launchd/systemd service env file (~/.openclaw/service-env/ai.openclaw.gateway.env), pointing at cordon’s CA so the gateway trusts cordon’s MITM certs. NODE_USE_SYSTEM_CA=1 keeps system roots loaded alongside the cordon CA, so non-cordon-fronted endpoints still validate normally.
Only NODE_EXTRA_CA_CERTS and NODE_USE_SYSTEM_CA survive OpenClaw’s service-env filter. Standard HTTPS_PROXY / HTTP_PROXY env vars are deliberately stripped (daemon/service-env.ts:readServiceProxyEnvironment) — only OPENCLAW_PROXY_URL is forwarded. Setup uses the config-driven path (proxy.proxyUrl in ~/.openclaw/openclaw.json) instead, which startProxy() reads at gateway startup.
For cordon’s matched-route TLS behavior and certificate troubleshooting, see TLS.

​
Browser tool

Older OpenClaw versions failed with a CDP 502 when using openclaw browser start with proxy.enabled=true. The gateway’s managed proxy was intercepting its own loopback CDP connection. This was fixed upstream — run openclaw upgrade to get the fix. If you’re on an older version and can’t upgrade immediately, you can use an external @playwright/mcp stdio MCP server via openclaw mcp add as a workaround — the stdio transport bypasses the managed proxy.

​
Workflow

Once configured, the workflow is:
  1. Start cordon: cordon start --config ~/.openclaw/cordon.toml (or use the background service)
  2. The OpenClaw daemon is already running (set up by cordon setup openclaw)
  3. When OpenClaw makes API calls to configured hosts, cordon transparently injects credentials
  4. OpenClaw never sees or logs real API keys
Use cordon doctor to diagnose any setup issues. It checks config validity, cert paths, trust store status, and port availability.

​
Troubleshooting

  1. Wrong header config: Anthropic uses type: header with header_name: x-api-key and no scheme. Check your cordon.toml route configuration.
  2. Missing dummy key: OpenClaw won’t select a provider without a value in env.vars (or the auth profile). Add ANTHROPIC_API_KEY=dummy-replaced-by-cordon (or equivalent) to ~/.openclaw/openclaw.json’s env.vars.
  3. Check the secret source: HTTP route secrets are fetched per-request — if you changed a secret, the next request picks it up automatically.
  4. Verify the secret is stored: cordon secret set anthropic
Verify the OpenClaw gateway’s launchd service env carries cordon’s CA:
grep NODE_EXTRA_CA_CERTS ~/.openclaw/service-env/ai.openclaw.gateway.env
The value should point at cordon’s ca-cert.pem. If empty or pointing at the macOS default (/etc/ssl/cert.pem), re-run cordon setup openclaw (it reinstalls the daemon with the correct env). Then follow TLS troubleshooting for runtime cert issues.
Confirm OpenClaw activated the managed proxy at startup. Tail the gateway log and look for the activation line:
grep "managed proxy" ~/.openclaw/logs/gateway.log
Expected: [proxy] routing process HTTP traffic through external proxy http://<audience>:<token>@127.0.0.1:<PORT>. If absent, verify openclaw config get proxy returns enabled: true and a valid proxyUrl. Then use the shared proxy not running checks with --config ~/.openclaw/cordon.toml.
Fixed in newer OpenClaw versions. Run openclaw upgrade to get the fix. If you can’t upgrade, see Browser tool above for a workaround.
Earlier versions of the integration could re-snapshot inherited NODE_EXTRA_CA_CERTS from the user’s shell into the new service env, even on cordon integration disable openclaw. The current setup explicitly strips those env vars from the install subprocess. If you upgraded from an earlier cordon, re-run cordon integration disable openclaw && cordon setup openclaw once to land the fix.
Restart Cordon after adding or editing route definitions. The OpenClaw gateway picks up cordon routes per-request, so it doesn’t need its own restart for route changes — only when proxy.enabled or proxy.proxyUrl themselves change. See Routes: route changes and secret rotation.