Inspired by Theo's original post on X.
The basic idea: if you prefer Claude Code's agent harness and terminal UX to the Codex CLI, claudex lets you keep Claude Code's interface, tools, permissions, plugins, and workflow while using GPT/Codex models underneath. A local CLIProxyAPI server translates and routes Claude Code's requests to a model available through Codex OAuth.
The important isolation rule is:
claudecontinues to work normally with its existing account and configuration.codexcontinues to work normally with its existing configuration.- Only
claudexuses the local proxy and the selected Codex model.
Set up a new `claudex` command on my machine. It must run the Claude Code CLI interface and tooling while using `gpt-5.6-sol` through my Codex OAuth account and a localhost-only CLIProxyAPI server.
Requirements:
1. Inspect before changing anything
- Locate `cli-proxy-api`, `claude`, and `codex` and report their versions.
- Inspect `cli-proxy-api --help` and any installed example config or systemd unit.
- Inspect my shell configuration for existing `claude`, `claudex`, or similar aliases/functions.
- Preserve all existing Claude Code and Codex behavior.
- Do not print existing OAuth tokens, API keys, or credential-file contents.
2. Install CLIProxyAPI if it is missing
- Use the official CLIProxyAPI quick-start documentation for the detected operating system. Do not invent package names or download URLs.
- macOS with Homebrew:
`brew install cliproxyapi`
Be aware that `brew services` expects its config at `$(brew --prefix)/etc/cliproxyapi.conf`. If this setup uses `~/.cli-proxy-api/config.yaml`, safely back up any existing Homebrew config and symlink that expected path to the user config before starting the service.
- Arch Linux:
`yay -S cli-proxy-api-bin`
or `paru -S cli-proxy-api-bin`
The package includes an example config and a systemd user service.
- Other Linux distributions:
use the official installer from `router-for-me/cliproxyapi-installer`. Download it to a temporary file, inspect it, then run it; do not blindly execute a remote script if the environment's security policy forbids that.
- Windows:
use the current binary from the official GitHub releases page. This particular `claudex` alias targets zsh on macOS/Linux/WSL; adapt it to a PowerShell function only if the user explicitly wants native Windows.
- Building from source is a fallback only when packages/releases are unsuitable; use the repository's documented `go build -o cli-proxy-api ./cmd/server` command and verify the required Go version first.
- After installation, run `cli-proxy-api --help` and record the installed version. Confirm that the build exposes Codex and Claude OAuth flags before continuing.
- Do not start the background service until a valid config file exists.
3. Configure CLIProxyAPI
- Use `~/.cli-proxy-api/config.yaml` unless the installed service requires another path.
- Bind only to `127.0.0.1` on port `8317`.
- Disable TLS for this localhost-only connection.
- Disable remote management and its control panel.
- Use `~/.cli-proxy-api` as the OAuth auth directory.
- Generate a new cryptographically random local API key. Never use an example or predictable key.
- Store the client copy in `~/.cli-proxy-api/client.key`, not directly in the shell alias.
- Set the directory to mode `0700` and all config, key, and OAuth JSON files to mode `0600`.
- Keep normal retry defaults and use round-robin routing with session affinity disabled.
The effective server config should be equivalent to:
host: "127.0.0.1"
port: 8317
tls:
enable: false
cert: ""
key: ""
remote-management:
allow-remote: false
secret-key: ""
disable-control-panel: true
auth-dir: "~/.cli-proxy-api"
api-keys:
- "GENERATE_A_RANDOM_LOCAL_KEY"
debug: false
logging-to-file: false
usage-statistics-enabled: false
request-retry: 3
max-retry-credentials: 0
max-retry-interval: 30
routing:
strategy: "round-robin"
session-affinity: false
ws-auth: true
4. Run it as a user service
- Prefer the systemd user unit included by the installed CLIProxyAPI package.
- If no unit exists, create a user unit whose ExecStart runs the discovered binary with `-config %h/.cli-proxy-api/config.yaml`, restarts on failure, and starts after the network is available.
- Run `systemctl --user daemon-reload` and enable/start the service.
- Verify it is active and listening only on `127.0.0.1:8317`.
5. Authenticate both upstream accounts
- Run the installed binary's Codex OAuth flow with the explicit config path. Current CLIProxyAPI builds use:
`cli-proxy-api -config ~/.cli-proxy-api/config.yaml -codex-login`
- Let me complete the browser approval when prompted.
- Run the Claude OAuth flow similarly:
`cli-proxy-api -config ~/.cli-proxy-api/config.yaml -claude-login`
- Let me complete that browser approval too.
- After each login, set newly created OAuth JSON files to mode `0600`.
- Confirm the service hot-loaded both credentials, restarting it only if necessary.
6. Add only the `claudex` alias
- Add the following logical alias to the correct zsh startup file, adapting paths if my shell or home layout differs:
alias claudex='ANTHROPIC_BASE_URL=http://127.0.0.1:8317 ANTHROPIC_AUTH_TOKEN="$(<"$HOME/.cli-proxy-api/client.key")" CLAUDE_CODE_SUBAGENT_MODEL=gpt-5.6-sol CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=3 ENABLE_TOOL_SEARCH=false claude --model gpt-5.6-sol'
- Keep these environment variables invocation-scoped. Do not export them globally and do not add them to `~/.claude/settings.json`.
- Preserve argument forwarding so commands such as `claudex --continue`, `claudex --resume`, and `claudex -p "..."` work.
- Do not redefine or wrap the normal `claude` or `codex` commands.
7. Verify the complete setup
- An unauthenticated request to `http://127.0.0.1:8317/v1/models` must be rejected.
- An authenticated request using `client.key` must succeed.
- Confirm the returned model catalog contains `gpt-5.6-sol` and Claude models.
- If `gpt-5.6-sol` is unavailable, stop and tell me; do not silently choose another model.
- Run `claudex --version` to confirm argument forwarding.
- Run one minimal request: `claudex -p "Reply with exactly: claudex route works"`.
- Require the exact successful response before declaring completion.
- Open a clean shell and prove `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` are unset globally.
- Prove normal `claude` and `codex` still resolve exactly as they did before.
- Report the final service status and credential permissions without revealing any secrets.
Security constraints:
- Never expose the proxy beyond localhost.
- Never commit, paste, log, or display the generated local key or OAuth credentials.
- Do not weaken TLS verification, Claude Code permissions, or sandbox settings.
- Do not overwrite whole config files when a narrow merge is possible.
- Ask me only for browser OAuth approval or genuinely missing product choices; handle discoverable machine details yourself.
ANTHROPIC_BASE_URLsends this Claude Code invocation to the local Anthropic-compatible proxy.ANTHROPIC_AUTH_TOKENauthenticates to the local proxy using a protected file.--model gpt-5.6-solselects the Codex-backed model for the main Claude Code session.CLAUDE_CODE_SUBAGENT_MODELkeeps Claude Code subagents on the same model.CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1enables effort controls for the custom model.CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=3caps concurrent tool calls.ENABLE_TOOL_SEARCH=falsedisables dynamic tool search on the non-Anthropic gateway.
Because all variables are attached to the alias invocation, they do not change the normal claude or codex environment.
claudex
claudex --continue
claudex --resume
claudex -p "Explain this repository"Model availability depends on the authenticated Codex account and the CLIProxyAPI version. Do not rename or silently substitute the requested model if it is missing from /v1/models.
CLIProxyAPI changes quickly, so check the linked quick-start page before copying a command.
brew install cliproxyapiWhen managed by brew services, Homebrew reads $(brew --prefix)/etc/cliproxyapi.conf. The official docs show how to symlink that path to ~/.cli-proxy-api/config.yaml if you want the same layout used in this guide.
yay -S cli-proxy-api-bin
# or
paru -S cli-proxy-api-binThe AUR package includes /usr/share/doc/cli-proxy-api-bin/config.example.yaml and a systemd user unit. Create the config before enabling the service.
The official quick start currently provides this installer:
curl -fsSL https://raw.githubusercontent.com/router-for-me/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bashFor a safer agent workflow, download the installer to a temporary file, inspect it, and then execute it instead of piping it directly to a shell.
Download the appropriate binary from the project's official GitHub releases. Native Windows needs a PowerShell equivalent of the zsh alias; WSL can follow the Linux/zsh flow.
- CLIProxyAPI repository
- CLIProxyAPI official quick start and installation
- CLIProxyAPI basic configuration
- CLIProxyAPI example configuration
- CLIProxyAPI Codex OAuth
- CLIProxyAPI Claude OAuth
- CLIProxyAPI Claude Code client configuration
- Claude Code environment variables
- Claude Code authentication and credential precedence
- Claude Code model configuration
- Original
claudexinspiration from Theo