Claudex

中文文档

Claude Code's shell. GPT-5.6 Sol's brain. One command.

Run OpenAI Codex subscription models inside Claude Code through a private, localhost-only CLIProxyAPI instance—without changing your existing Claude Code or Codex setup.

“If this gets blocked, I owe you a reset.”

— Tibo, after sharing the original three-step claudex recipe

Install

curl -fsSL https://github.com/liuzhao1225/claudex/releases/latest/download/install.sh | bash

Claude Code orchestration · Codex models · localhost-only · reversible install

[!CAUTION] Claudex is an unofficial community project. Tibo's post is personal commentary—not an OpenAI policy statement, terms exception, endorsement, or account-safety guarantee. Anthropic does not support routing Claude Code to non-Claude models through a gateway. Using this project may put your account at risk; read Account and policy risk before installing.

Requirements

• macOS or Linux on arm64 or x86_64
• Claude Code
• A ChatGPT account with Codex access
• curl, tar, and either shasum or sha256sum

The installer downloads a checksum-pinned CLIProxyAPI binary into Claudex's private data directory, creates a localhost-only configuration, opens Codex OAuth, starts the proxy, and verifies that gpt-5.6-sol is available. OAuth authorization in the browser still requires your interaction.

Then launch Claude Code with:

claudex

If Claudex saved you setup time, consider starring the repository.

Claude Code is required. The installer stops without changing anything if it is missing and prints its official installation link. The Codex CLI is optional because CLIProxyAPI performs its own OAuth flow; when it is missing, Claudex prints the official Codex installation link and continues.

What it changes

Claudex's primary installation files are kept under these user-scoped paths:

~/.local/bin/claudex
~/.config/claudex/
~/.local/share/claudex/
~/.local/state/claudex/

The corresponding XDG environment variables are respected. The only additional touchpoint is shell configuration: if ~/.local/bin is not on PATH, the installer adds one marked, reversible block to the current zsh or Bash configuration after creating a timestamped backup next to that file.

Claudex does not:

• modify Claude Code or Codex configuration;
• read or copy ~/.codex/auth.json;
• reuse, overwrite, or stop another CLIProxyAPI installation;
• install a login service, LaunchAgent, or systemd unit;
• expose the proxy outside 127.0.0.1;
• update itself silently.

Commands

claudex [Claude Code arguments...]       Start Claude Code through the private proxy
claudex -- [Claude Code arguments...]     Bypass management-command name matching
claudex setup [--model MODEL]             Repair setup, redo OAuth, and verify a model
claudex login [--no-browser]              Redo Codex OAuth
claudex doctor                            Run redacted diagnostics
claudex start|stop|restart|status         Manage the private proxy process
claudex update                            Install the latest checksum-checked Claudex release
claudex rollback                          Restore the previous installed version
claudex uninstall [--keep-auth]           Remove Claudex; optionally preserve OAuth files
claudex version                           Print Claudex and CLIProxyAPI versions

The default model is gpt-5.6-sol. An explicit Claude Code --model argument is preserved and is never duplicated.

At launch, Claudex sets gateway and model variables only for the child claude process:

• ANTHROPIC_BASE_URL
• ANTHROPIC_AUTH_TOKEN
• ANTHROPIC_MODEL
• ANTHROPIC_DEFAULT_OPUS_MODEL
• ANTHROPIC_DEFAULT_SONNET_MODEL
• ANTHROPIC_DEFAULT_HAIKU_MODEL
• CLAUDE_CODE_SUBAGENT_MODEL

It deliberately does not reproduce the original post's extra behavior and performance overrides: always-on effort, fixed tool concurrency, and disabled Tool Search. Some of those controls are now documented by Anthropic, but they are outside Claudex's minimal, locally tested gateway configuration.

Security model

• CLIProxyAPI is pinned to a version tested with each Claudex release.
• Every upstream archive is verified against a repository-reviewed SHA-256 lock before extraction.
• The proxy binds only to 127.0.0.1; its management API and control panel are disabled.
• A random 256-bit local API token is stored in a 0600 file and is never printed by doctor.
• Configuration, OAuth, runtime, and state directories are private to the current user.
• Claudex resolves and exactly matches both the saved PID and the private executable path before stopping a process.
• Updates are explicit, staged, checksum-checked, and restore the previous installed version if installation or the post-update health check fails. A proxy that was stopped before the update is stopped again after verification.

The proxy itself still sends prompts and credentials to the selected upstream services. Review CLIProxyAPI before trusting it with an account or source code.

Verified installation

The one-line installer is a convenience bootstrap. For an auditable installation, verify the immutable release and build attestation first:

version=v0.1.1

gh release download "$version" \
  --repo liuzhao1225/claudex \
  --pattern install.sh \
  --pattern SHA256SUMS

expected=$(awk '$2 == "install.sh" { print $1 }' SHA256SUMS)
if command -v shasum >/dev/null 2>&1; then
  actual=$(shasum -a 256 install.sh | awk '{ print $1 }')
else
  actual=$(sha256sum install.sh | awk '{ print $1 }')
fi
test -n "$expected" && test "$actual" = "$expected"

gh release verify "$version" --repo liuzhao1225/claudex
gh release verify-asset "$version" install.sh --repo liuzhao1225/claudex
gh attestation verify install.sh \
  --repo liuzhao1225/claudex \
  --signer-workflow liuzhao1225/claudex/.github/workflows/release.yml

bash install.sh

Troubleshooting

Run:

claudex doctor
claudex status

Common failures:

• Port 1455 is occupied: Codex OAuth needs its callback listener. Stop that listener and rerun claudex login.
• Port 8317 is occupied: initial setup selects the next free port through 8399. If the persisted port is later taken by another program, rerun claudex setup.
• gpt-5.6-sol is absent: the installer reports the available gpt-* models and exits nonzero. Claudex never silently substitutes a model.
• Headless Linux: use claudex setup --no-browser or claudex login --no-browser and follow the URL printed by CLIProxyAPI.

The private proxy log is stored under the Claudex XDG state directory and is rotated at 1 MiB. doctor never prints log contents or credentials.

Account and policy risk

The technique was publicly discussed by Theo and Tibo and implemented by the third-party CLIProxyAPI project. Those posts are not product documentation, a terms exception, an account-safety guarantee, or an official approval of subscription proxying.

• Theo's original experience report
• Tibo asking for the recipe
• Theo's short recipe
• Tibo's three-step post
• CLIProxyAPI Codex OAuth documentation
• CLIProxyAPI Claude Code documentation

Before using Claudex, review the current provider documents yourself:

• Anthropic: LLM gateway configuration and unsupported non-Claude routing
• Anthropic: connecting Claude Code to a gateway
• OpenAI: using Codex with a ChatGPT plan
• OpenAI: ChatGPT Pro plan restrictions
• OpenAI Terms of Use

Plan-specific guidance differs across Plus, Pro, Business, Enterprise, and other account types. Policies and product behavior can change at any time. You are responsible for deciding whether your use complies with the agreements and plan guidance that apply to your account.

Development

shellcheck install.sh bin/claudex scripts/*.sh
shfmt -d -i 2 -ci install.sh bin/claudex scripts/*.sh
bats tests
./scripts/verify-dependency-lock.sh
./scripts/package.sh v0.1.1 dist

See SECURITY.md for vulnerability reporting. Claudex is available under the MIT License.

Star History