Zero-Trust AI Gateway
for Teams That Can't Compromise

Prerequisites

• A running Corveil instance (see deployment options above)
• A Corveil virtual API key (sk-corveil-...) — create one from the Corveil admin panel or CLI
• Claude Code installed

1. Configure Claude Code

Corveil supports two authentication modes. Choose the one that fits your setup:

Option A: Direct API Key (Corveil manages the Anthropic key)

Your ANTHROPIC_API_KEY is a Corveil virtual key. Corveil authenticates the request and forwards it upstream using its own provider credentials.

export ANTHROPIC_BASE_URL="https://your-corveil-host"
export ANTHROPIC_API_KEY="sk-corveil-your-key-here"

Or configure via settings.json (project .claude/settings.json or global ~/.claude/settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-corveil-host",
    "ANTHROPIC_API_KEY": "sk-corveil-your-key-here"
  }
}

Option B: Passthrough (use your own Claude subscription)

Your own Anthropic API key or OAuth token is sent directly to Anthropic. A separate x-corveil-api-key header authenticates with Corveil for tracking and guardrails.

export ANTHROPIC_BASE_URL="https://your-corveil-host"
export ANTHROPIC_CUSTOM_HEADERS="x-corveil-api-key: sk-corveil-your-key-here"

Or configure via settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-corveil-host",
    "ANTHROPIC_CUSTOM_HEADERS": "x-corveil-api-key: sk-corveil-your-key-here"
  }
}

These can be set in Claude Code's settings file at the project level (.claude/settings.json) or globally (~/.claude/settings.json). See the Claude Code settings documentation for details.

Replace your-corveil-host with your Corveil URL and sk-corveil-your-key-here with your virtual API key. If using env vars, reload your shell or run source ~/.zshrc.

2. Launch Claude Code

Start Claude Code as usual — it will automatically route all requests through Corveil:

claude

3. Verify the connection

Ask Claude Code a simple question. If it responds, requests are flowing through Corveil. You can confirm by checking the Corveil dashboard or logs for the incoming request.

# Check Corveil logs for the request
corveil logs --tail 5

How it works

Claude Code natively supports the ANTHROPIC_BASE_URL environment variable. When set, all API requests are sent to that URL instead of the default api.anthropic.com:

• Routing: Claude Code sends all Anthropic API requests to your Corveil host
• Direct mode (Option A): ANTHROPIC_API_KEY is sent as the standard x-api-key header. Corveil uses it for auth, spend tracking, and policy enforcement, then forwards the request upstream using its own provider credentials
• Passthrough mode (Option B): x-corveil-api-key (via ANTHROPIC_CUSTOM_HEADERS) authenticates with Corveil for tracking and guardrails. The user's own OAuth token or API key flows through the Authorization header to Anthropic
• Full visibility: In both modes, every request and response is logged, guardrails are enforced, and costs are tracked — all transparent to the Claude Code user

Troubleshooting

• 401 Unauthorized (Direct mode): Verify your ANTHROPIC_API_KEY matches a valid Corveil virtual API key
• 401 Unauthorized (Passthrough mode): Verify your x-corveil-api-key header value is a valid Corveil virtual API key, and that your Anthropic credentials are valid
• Connection refused: Ensure your Corveil instance is running and the ANTHROPIC_BASE_URL is reachable
• Environment not picked up: Make sure you reloaded your shell after adding the exports, or set them in the same terminal session. If using settings.json, ensure the file is valid JSON and in the correct location
• Custom headers not sent: Verify ANTHROPIC_CUSTOM_HEADERS uses the format header-name: value (colon-space separated)
• Model not available: Ensure your Corveil instance has the requested Anthropic models configured in its provider settings

Prerequisites

• A running Corveil instance (see deployment options above)
• A Corveil virtual API key (sk-corveil-...) — create one from the Corveil admin panel or CLI
• OpenClaw installed and running (openclaw gateway run or the Mac app)
• An existing Anthropic API key or OAuth session configured in OpenClaw

1. Configure the Anthropic provider

Tell OpenClaw to route Anthropic requests through Corveil by setting a custom baseUrl and adding your Corveil API key as a header. This uses OpenClaw's passthrough mode — your existing Anthropic credentials are forwarded upstream automatically.

openclaw config set models.providers.anthropic '{
  "baseUrl": "https://your-corveil-host",
  "api": "anthropic-messages",
  "headers": {
    "x-corveil-api-key": "sk-corveil-your-key-here"
  },
  "models": [
    {
      "id": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",
      "reasoning": true,
      "input": ["text", "image"],
      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
      "contextWindow": 200000,
      "maxTokens": 16384
    }
  ]
}'

Replace your-corveil-host with your Corveil URL and sk-corveil-your-key-here with the virtual API key you created. Add additional models to the models array as needed. Setting costs to 0 is recommended since Corveil tracks spend on its side.

2. Restart the gateway

The configuration change requires a gateway restart to take effect:

# If using the Mac app, restart from the menu bar
# Otherwise:
openclaw gateway restart

3. Verify the connection

Check that the provider is configured and reachable:

# Check provider status
openclaw channels status --probe

# Send a test message
openclaw message send "Hello from OpenClaw via Corveil"

If the message goes through, every request is now flowing through Corveil with spend tracking, logging, and guardrails active.

How passthrough mode works

OpenClaw's passthrough mode lets Corveil sit transparently between OpenClaw and the upstream AI provider:

• Routing: OpenClaw sends requests to your Corveil host instead of directly to api.anthropic.com
• Corveil auth: The x-corveil-api-key header authenticates the request with Corveil for spend tracking and policy enforcement
• Upstream auth: Your existing Anthropic credentials (OAuth token or API key) are forwarded to the upstream provider automatically — Corveil does not need to store provider keys
• Full visibility: Corveil logs every request/response, enforces guardrails, and tracks costs — all without changing how OpenClaw handles conversations

Troubleshooting

• 401 Unauthorized from Corveil: Verify your x-corveil-api-key is valid and has not expired
• 401 from upstream provider: Check that your Anthropic credentials are still configured in OpenClaw (openclaw config get models.providers.anthropic)
• Connection refused: Ensure your Corveil instance is running and the baseUrl is reachable from the machine running OpenClaw
• Model not found: The model IDs in your config must match models available through your Corveil instance