Configuration & Usage

Modes

clawgate has two modes of operation:

ChatGPT mode (default)

Uses your existing ChatGPT Plus or Pro subscription. No API key needed.

# First time: log in
clawgate login

# Then run the proxy
clawgate

The login flow opens a browser-based OAuth authorization page. You enter a code shown in your terminal, approve the connection, and clawgate saves the token to ~/.clawgate/token.json. Tokens auto-refresh when they expire.

API key mode

Uses a standard OpenAI (or compatible) API key. No login step needed.

clawgate --mode=api --apiKey=sk-xxx

This mode works with any OpenAI-compatible endpoint, including:

• OpenAI API
• Azure OpenAI
• Local inference servers (vLLM, Ollama with OpenAI compat, etc.)
• Any service that speaks the OpenAI Chat Completions format

To use a custom endpoint:

clawgate --mode=api --apiKey=sk-xxx --baseUrl=https://my.endpoint/v1

CLI flags

All flags are optional. Flags take precedence over environment variables.

Both single-dash and double-dash work: --mode=api and -mode=api are equivalent. Both --flag=value and --flag value forms are accepted.

Subcommands

login flags

logout flags

status flags

Account management

clawgate supports multiple ChatGPT accounts side by side. Each account keeps its own OAuth token and can be selected per proxy run without disturbing the persistent default.

# First login creates an account named "default" and makes it default
clawgate login

# Add a second account
clawgate login --name work

# Add a third and immediately make it default
clawgate login --name personal --default

# List all accounts (* marks the default)
clawgate account list

# Switch the persistent default
clawgate account use work

# Start the proxy using a non-default account for this run only
clawgate --account personal

# Check a specific account's token status
clawgate status --account work

# Remove a single account
clawgate logout --account work

# Remove everything
clawgate logout --all

Account name rules: lowercase letters, digits, ., _, or -, starting with a letter or digit, 1–32 characters. The name all is reserved.

Rules:

• clawgate login with no --name re-authenticates the current default (or creates one named default on first use).
• First account ever saved automatically becomes the default.
• --account NAME on a proxy run is a one-run override; it does NOT change the persistent default.
• Removing the default account leaves default_account empty; the next run asks you to pick one with clawgate account use NAME.
• In API key mode, --account is ignored — no auth store is involved.

Environment variables

Environment variables work as a fallback when flags are not set. Useful for CI/CD, Docker, and other automated setups.

You can also place these in a .env file in the working directory.

Precedence order: CLI flag > environment variable > .env file > default.

Example using environment variables:

AUTH_MODE=apikey OPENAI_API_KEY=sk-xxx clawgate

Running in the background

On macOS/Linux, you can run clawgate as a long-lived background process:

CLAWGATE_LOG=/tmp/clawgate.log nohup clawgate >/dev/null 2>&1 &

clawgate explicitly ignores SIGHUP so closing the terminal does not stop it. CLAWGATE_LOG applies only when starting the proxy (not to login, status, account, logout, or help subcommands). It mirrors every Go-level write to os.Stdout and os.Stderr — including the banner, per-request lines, and DEBUG dumps — into the named file in append mode. Standard > redirection still works for users who prefer it.

The log file is opened with mode 0600 (user-only) because DEBUG=1 dumps may contain request/response bodies. Do not point CLAWGATE_LOG at the same path you also redirect stdout/stderr to — each line would be written twice.

Model mapping

clawgate maps Anthropic model names to OpenAI model names:

The anthropic/, openai/, and gemini/ prefixes are stripped before matching, so anthropic/claude-3-5-sonnet and claude-3-5-sonnet both route to the same model.

Override the defaults:

ChatGPT mode — the Codex backend only accepts a fixed set of models: gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2-codex, gpt-5.3-codex, gpt-5.4. clawgate prints a warning at startup if you pick anything else.

clawgate --bigModel=gpt-5.4 --midModel=gpt-5.3-codex --smallModel=gpt-5.2-codex

API key mode — any model your endpoint supports works:

clawgate --mode=api --apiKey=sk-xxx --bigModel=gpt-4o --midModel=gpt-4o --smallModel=gpt-4o-mini

Reasoning effort

GPT-5 and o-series models accept a reasoning_effort knob that trades quality for cost/latency. clawgate exposes it as --reason (env REASON), using Codex CLI’s exact vocabulary so values transfer verbatim:

clawgate --reason=high
clawgate --mode=api --apiKey=sk-xxx --reason=minimal

Precedence: if both --reason and per-request thinking (budget_tokens) are set, whichever maps to the higher effort wins. If only one is set, that value applies. If neither is set, the proxy leaves the field unset and upstream uses its model default (typically medium).

The budget-to-effort mapping used for per-request thinking:

The flag is silently ignored for non-reasoning models such as gpt-4o or gpt-4. Unknown values trigger a startup warning but are still forwarded — the upstream catalog may grow without a proxy release.

Connecting Claude Code

Once clawgate is running, point Claude Code at it by setting the ANTHROPIC_BASE_URL environment variable:

ANTHROPIC_BASE_URL=http://localhost:8082 claude

On Windows (Command Prompt):

set ANTHROPIC_BASE_URL=http://localhost:8082
claude

On Windows (PowerShell):

$env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude

If you changed the port with --port, adjust the URL accordingly.

Debug mode

Set DEBUG=1 to log all incoming Anthropic requests and outgoing OpenAI requests to the console:

DEBUG=1 clawgate

This is useful for troubleshooting request translation issues or verifying that tool calls are mapped correctly.

Examples

# ChatGPT mode, default settings
clawgate

# API key mode, default models
clawgate --mode=api --apiKey=sk-xxx

# Custom models and port
clawgate --mode=api --apiKey=sk-xxx --bigModel=gpt-4o --smallModel=gpt-4o-mini --port=9000

# Azure OpenAI
clawgate --mode=api --apiKey=xxx --baseUrl=https://myresource.openai.azure.com/openai/deployments/gpt-4o/v1

# Local vLLM
clawgate --mode=api --apiKey=dummy --baseUrl=http://localhost:8000/v1

# Docker / CI (environment variables)
AUTH_MODE=apikey OPENAI_API_KEY=sk-xxx PORT=8082 clawgate

Files and directories

Troubleshooting

“command not found” after install Close and reopen your terminal. If it still doesn’t work, verify that the directory containing the clawgate binary is in your PATH.

“Not logged in” error Run clawgate login to authenticate.

“API key is required” error Pass --apiKey=sk-... when using --mode=api, or set the OPENAI_API_KEY environment variable.

macOS “unidentified developer” dialog Run xattr -d com.apple.quarantine clawgate before first use. See the macOS install guide for details.

Windows SmartScreen warning Click “More info” then “Run anyway”. See the Windows install guide for details.

429 / rate limit errors clawgate retries rate-limited requests automatically (up to 3 times with backoff). If you see persistent 429s, you’re hitting the upstream provider’s rate limit – wait a moment or reduce request frequency.