The shape of it
Claude Code is the client. CLIProxyAPI is the local adapter.
The terminal UX, tools, sessions, and permission model you already know.
A service on your Mac that adapts Claude-compatible requests to your authenticated Codex account.
Local means local. This guide binds the proxy to 127.0.0.1, so only programs running on this Mac can reach it. It does not expose a LAN, VPN, or public endpoint.
Before starting, make sure Homebrew, the claude command, and an OpenAI/Codex account you are authorised to use are available on the Mac.
Step 1
Install and start CLIProxyAPI.
Install with Homebrew
The Homebrew formula also provides a user service.
brew install cliproxyapi
brew services start cliproxyapiHomebrew uses a fixed service config path. On Apple Silicon it is normally /opt/homebrew/etc/cliproxyapi.conf; on Intel it is normally /usr/local/etc/cliproxyapi.conf. The commands below use $(brew --prefix) so they work on both.
Step 2
Give the service a local-only config and client key.
First generate a long, unique API key. This is the key that local clients use to talk to your proxy. Save it somewhere private for the next step; do not paste a real value into this guide, a shell history, chat, or a repository.
openssl rand -hex 32Create the config
Replace PASTE_YOUR_LONG_RANDOM_KEY_HERE with the value you just generated. The host line is the important security boundary.
host: "127.0.0.1"
port: 8317
auth-dir: "~/.cli-proxy-api"
api-keys:
- "PASTE_YOUR_LONG_RANDOM_KEY_HERE"
remote-management:
allow-remote: false
secret-key: ""mkdir -p ~/.cli-proxy-api
nano "$(brew --prefix)/etc/cliproxyapi.conf"
brew services restart cliproxyapiWhy this config? An empty host can bind every interface. 127.0.0.1 deliberately prevents that. An empty management secret-key disables the management API.
Step 3
Connect the proxy to OpenAI/Codex.
Run the interactive Codex login on this same Mac. Follow the browser flow and return to the terminal when it completes. The resulting OAuth state stays under ~/.cli-proxy-api.
cli-proxy-api -codex-login -config "$(brew --prefix)/etc/cliproxyapi.conf"If your installed binary does not recognise that command, check its local help first:
cli-proxy-api --helpOAuth is not your proxy API key. The browser sign-in authorises the upstream OpenAI/Codex account. The local key from Step 2 protects access to the proxy on your Mac. You need both.
Step 4
Add the claudex launcher.
Put the local client key in a file with owner-only permissions, then add a small wrapper to your PATH. This keeps the key out of the launcher source and gives Claude Code its three model slots.
mkdir -p ~/.config/claudex ~/.local/bin
chmod 700 ~/.config/claudex
nano ~/.config/claudex/client-key
chmod 600 ~/.config/claudex/client-keyPaste the same random key from Step 2 into ~/.config/claudex/client-key, save, then create ~/.local/bin/claudex with the following contents:
#!/usr/bin/env zsh
set -euo pipefail
key_file="${CLAUDEX_API_KEY_FILE:-$HOME/.config/claudex/client-key}"
[[ -r "$key_file" ]] || {
print -u2 "claudex: cannot read $key_file"
exit 1
}
export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"
export ANTHROPIC_AUTH_TOKEN="$( < "$key_file")"
# Claude Code custom slots. [1m] enables its extended-context classification.
export ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5.6-sol[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5.6-terra[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5.6-luna"
export CLAUDE_CODE_SUBAGENT_MODEL="opus"
# Codex-like context management.
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=258400
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90
# Select the Opus slot explicitly. Do not set ANTHROPIC_MODEL here:
# it produces a duplicate Sol entry in Claude Code's model picker.
exec claude --model opus "$@"chmod 700 ~/.local/bin/claudex
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc| Claude Code slot | CLIProxyAPI model | Use |
|---|---|---|
| Opus / main | gpt-5.6-sol[1m] | Default claudex model |
| Subagents | gpt-5.6-sol[1m] via opus | Delegated Claude Code work |
| Sonnet | gpt-5.6-terra[1m] | Choose the Sonnet slot when appropriate |
| Haiku | gpt-5.6-luna | Fast, lighter work |
[1m] is a Claude Code custom-model marker: it gives Sol and Terra the extended-context classification, while the proxy receives the underlying model name. The explicit compaction variables still govern the working window: 258,400 tokens with auto-compaction at 90%.
Working as a team
Give Claude Code clear rules for models and subagents.
Add the following to your global ~/.claude/CLAUDE.md. It travels with every Claude Code session on your Mac, so the agent has the same cost, quality, and delegation guardrails regardless of the repository you open.
# Subagents and cost control
Default to a single agent. Do not spawn subagents unless the user explicitly asks, or the task cleanly splits into independent workstreams. Treat spawning as expensive.
Hard limits unless the user overrides in this turn:
- Max concurrent subagents: 3
- Max nesting depth: 1 (subagents must not spawn further subagents)
- Max subagents per user request: 5
- Prefer one thorough pass over many overlapping auditors
Model routing:
- Exploration, linewise review, and convention scans: use the cheapest capable model (Luna or Terra), not Sol.
- Use Sol only for hard architecture, ambiguous debugging, or when the user asks.
- Never use maximum effort on bulk audit fan-out.
Audit and review rules:
- Do not fan out one agent per invariant, file, or convention check.
- One reviewer returns a deduplicated findings list with file references and severity.
- If rate-limited, stop spawning and report partial results; do not retry-swarm.
- Overlapping review tasks are forbidden; partition ownership if parallelising.
- If the user says “audit”, “review”, or “validate” without “parallel” or “subagents”, use exactly 0 subagents.
When in doubt, stay in the main session and use tools directly.Why add this? It prevents expensive or overlapping delegation from becoming the default, while preserving Sol for the work where its extra capability matters. It also makes routine review behaviour predictable: one accountable pass, concise findings, and no retry swarm when capacity is limited.
| In this guide | Use it for | Why |
|---|---|---|
| Luna | Lightweight exploration and straightforward checks | Fastest, lowest-cost option. |
| Terra | Line-by-line review and convention scans | Strong routine-reasoning default without escalating to Sol. |
| Sol | Hard architecture, ambiguous debugging, explicit requests | Reserve the flagship model for work that materially benefits from it. |
Step 5
Verify the whole path.
Check that the service is running and loopback-only
brew services list | rg cliproxyapi
lsof -nP -iTCP:8317 -sTCP:LISTENThe listener should show 127.0.0.1:8317, not *:8317 or a LAN address.
Confirm the proxy sees models
key="$(tr -d '\r\n' < ~/.config/claudex/client-key)"
curl -fsS -H "Authorization: Bearer $key" http://127.0.0.1:8317/v1/models \
| jq -r '.data[].id' | sortYou should see the model IDs your account exposes, including the Sol, Terra, and Luna aliases used by the wrapper.
Start Claude Code through the wrapper
claudexUse claudex --continue for an existing session; all other arguments pass straight through to claude.
Optional
Add cxyolo for an explicit permission bypass.
Add this alias to ~/.zshrc if you want a deliberate shortcut that keeps the same model routing but skips Claude Code permission prompts.
alias cxyolo='CLAUDE_CODE_NO_FLICKER=1 claudex --dangerously-skip-permissions'Use with intent. cxyolo authorises tool use without the usual approval gates. Use it only in a trusted directory, after checking the working tree and understanding any command that could modify, delete, or publish data. It is not a convenience default.
When it does not work
Short diagnostic loop.
Run brew services restart cliproxyapi, then confirm the listener with lsof. Inspect Homebrew service logs with brew services list and the service plist if needed.
Confirm the key in ~/.config/claudex/client-key exactly matches the config api-keys value. Check for an extra newline or pasted quote.
Run the model-list command above. If the aliases are absent, finish or renew the local Codex login, then review the proxy configuration and available account models.
Remove any ANTHROPIC_MODEL export from your shell config. The wrapper should use claude --model opus and the three ANTHROPIC_DEFAULT_* slot variables only.
Security boundary
Never share these secrets.
Do not send, commit, screenshot, or paste any of the following into tickets or chat:
- The value in
api-keysor~/.config/claudex/client-key - Anything under
~/.cli-proxy-api, especially OAuth/session files - Terminal history containing those values
- Service logs that may contain authentication details
If a key is exposed, replace it in the proxy config, update the local client-key file, restart the service, and revoke or renew the upstream account session as appropriate.