Skip to content

Instantly share code, notes, and snippets.

@krankos
Last active August 8, 2026 09:15
Show Gist options
  • Select an option

  • Save krankos/9925f7e29e3980f8525e67445ae453f2 to your computer and use it in GitHub Desktop.

Select an option

Save krankos/9925f7e29e3980f8525e67445ae453f2 to your computer and use it in GitHub Desktop.
claudex: use Claude Code's interface with GPT/Codex models through CLIProxyAPI

claudex: use Claude Code's interface with a Codex model through CLIProxyAPI

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:

  • claude continues to work normally with its existing account and configuration.
  • codex continues to work normally with its existing configuration.
  • Only claudex uses the local proxy and the selected Codex model.

Copy this prompt and give it to your coding agent

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.

What the alias does

  • ANTHROPIC_BASE_URL sends this Claude Code invocation to the local Anthropic-compatible proxy.
  • ANTHROPIC_AUTH_TOKEN authenticates to the local proxy using a protected file.
  • --model gpt-5.6-sol selects the Codex-backed model for the main Claude Code session.
  • CLAUDE_CODE_SUBAGENT_MODEL keeps Claude Code subagents on the same model.
  • CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 enables effort controls for the custom model.
  • CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=3 caps concurrent tool calls.
  • ENABLE_TOOL_SEARCH=false disables 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.

Usage

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.

Installation commands from the official quick start

CLIProxyAPI changes quickly, so check the linked quick-start page before copying a command.

macOS

brew install cliproxyapi

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

Arch Linux

yay -S cli-proxy-api-bin
# or
paru -S cli-proxy-api-bin

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

Other Linux distributions

The official quick start currently provides this installer:

curl -fsSL https://raw.githubusercontent.com/router-for-me/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash

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

Windows or manual installation

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.

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment