> ## 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.

# OpenClaw

> Set up cordon to give OpenClaw secure API access without exposing secrets.

Cordon integrates with [OpenClaw](https://openclaw.ai) 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](/configuration/overview#scopes) for path details and trade-offs.

## Automated setup

The fastest way to get started:

```bash theme={null}
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. Creates `tokens.toml` with a default token (if one doesn't already exist), plus an `openclaw` client token — see [Token migration](/guides/token-migration) — used to build the authenticated `proxy.proxyUrl` in the next step
5. Writes `proxy.enabled=true` and the authenticated `proxy.proxyUrl` directly to `~/.openclaw/openclaw.json`
6. 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
7. Restarts the daemon so the new proxy config takes effect
8. Probes the daemon with `openclaw daemon status` as a smoke test
9. Installs a cordon agent skill to `~/.openclaw/skills/cordon/SKILL.md`
10. Offers to add routes and store secrets interactively (post-setup wizard)

The daemon reinstall is the disruptive step — the OpenClaw gateway is stopped and restarted as part of setup. Active sessions are interrupted.

`cordon setup openclaw` also prompts "Install as a background service so cordon starts automatically?" (default No). Answer yes, or pass `--service` to install non-interactively. If you skipped it, run `cordon service install --config ~/.openclaw/cordon.toml` afterward.

### Remove the setup

```bash theme={null}
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`](/cli/route) and, if using the keyring secret source, store the credential with [`cordon secret set`](/cli/secret). Pass `--config ~/.openclaw/cordon.toml` to `cordon route`, `cordon start`, and `cordon service` commands so they target the OpenClaw config.

<Warning>
  Anthropic uses `type: header` with `header_name: x-api-key` and no `scheme`. Using an `Authorization` header will result in 401 errors.
</Warning>

## 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:

```jsonc theme={null}
{
  "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:

```bash theme={null}
# 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()`](https://github.com/openclaw/openclaw/blob/main/src/infra/net/proxy/proxy-lifecycle.ts) 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.

<Note>
  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.
</Note>

For cordon's matched-route TLS behavior and certificate troubleshooting, see [TLS](/configuration/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](https://github.com/openclaw/openclaw/pull/83255) — 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 that fully match configured routes, cordon transparently injects credentials
4. OpenClaw never sees or logs real API keys

<Tip>
  Use `cordon doctor` to diagnose any setup issues. It checks config validity, cert paths, trust store status, and port availability.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized errors">
    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`
  </Accordion>

  <Accordion title="Certificate errors">
    Verify the OpenClaw gateway's launchd service env carries cordon's CA:

    ```bash theme={null}
    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](/configuration/tls#troubleshooting-certificate-errors) for runtime cert issues.
  </Accordion>

  <Accordion title="Proxy not being used">
    Confirm OpenClaw activated the managed proxy at startup. Tail the gateway log and look for the activation line:

    ```bash theme={null}
    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](/guides/process-management#proxy-not-running-checks) with `--config ~/.openclaw/cordon.toml`.
  </Accordion>

  <Accordion title="`openclaw browser start` fails with CDP 502">
    Fixed in newer OpenClaw versions. Run `openclaw upgrade` to get the fix. If you can't upgrade, see [Browser tool](#browser-tool) above for a workaround.
  </Accordion>

  <Accordion title="Teardown leaves cordon's CA in service env">
    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.
  </Accordion>

  <Accordion title="Service restart required after config changes">
    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](/configuration/routes#route-changes-and-secret-rotation).
  </Accordion>
</AccordionGroup>