claudex-gateway

name

claudex-gateway

description

Bootstrap, maintain, and troubleshoot a local `claudex` stack that routes Claude Code through CLIProxyAPI into Codex OAuth / ChatGPT Codex. Use when setting up a new machine, creating the `claudex` wrapper and gateway runtime, repairing or changing the proxy on `127.0.0.1:8327`, adjusting the model-effort mapping for Opus/Sonnet/Haiku, syncing auth from `~/.codex/auth.json`, or explaining why LiteLLM fails but the CLIProxyAPI path works.

Claudex Gateway

Overview

Use this skill to operate the user's local Claude Code -> Codex OAuth gateway safely and consistently. Treat the deployed stack under CLAUDEX_GATEWAY_HOME as the source of truth unless the user explicitly asks to redesign it. For this skill, use these conventions:

• SKILL_ROOT: the installed path of this claudex-gateway skill directory
• CLAUDEX_GATEWAY_HOME: the runtime directory for the local proxy stack. If unset, the helper scripts look first in ${XDG_DATA_HOME:-$HOME/.local/share}/claudex-gateway and then in the legacy ${XDG_DATA_HOME:-$HOME/.local/share}/cliproxyapi-codex-test
• CLAUDEX_WRAPPER: the claudex wrapper path. If unset, default to ${HOME}/.local/bin/claudex

Quick Start

• Bootstrap a fresh machine: python3 "$SKILL_ROOT/scripts/bootstrap_stack.py"
• Refresh the local auth file from ~/.codex/auth.json: python3 "$SKILL_ROOT/scripts/sync_codex_auth.py"
• Check current gateway status: claudex status
• Restart the local proxy: claudex restart
• Smoke test the stack: python3 "$SKILL_ROOT/scripts/probe_stack.py"
• Launch Claude Code through the wrapper: claudex --resume

Workflow

0. Bootstrap first if the gateway stack does not exist yet

• If CLAUDEX_GATEWAY_HOME is missing, do not hand-roll files one by one.
• Run python3 "$SKILL_ROOT/scripts/bootstrap_stack.py" to create the runtime directory, config, launcher, env file, a claudex wrapper with status/start/stop/restart, and a built cli-proxy-api binary.
• The bootstrap script assumes: codex and claude are already installed git and go are available for cloning and building CLIProxyAPI
• After bootstrap, sync auth and start the proxy before debugging anything else.

1. Confirm which path is in play

• Assume the working path is: Claude Code -> claudex wrapper -> CLIProxyAPI -> chatgpt.com/backend-api/codex
• Do not start from LiteLLM when the user is asking about the current claudex setup.
• Read current-stack.md before changing architecture or explaining tradeoffs.

2. Refresh credentials first when behavior looks stale

• Run python3 "$SKILL_ROOT/scripts/sync_codex_auth.py"
• This copies the current Codex OAuth tokens from ~/.codex/auth.json into the proxy auth file: "$CLAUDEX_GATEWAY_HOME/auth/codex-current.json"
• If the user is logged out of Codex, stop and re-auth that first.

3. Verify the local proxy before touching Claude Code

• Prefer wrapper commands over raw runner calls: claudex status claudex start claudex restart
• Probe health, /v1/messages, tool use, and count tokens: python3 "$SKILL_ROOT/scripts/probe_stack.py"
• Use raw run.sh only when debugging wrapper generation itself.

4. Change model routing only in the env file unless the user asks for deeper changes

• The wrapper claudex sources: "$CLAUDEX_GATEWAY_HOME/claude-code-gpt54.env"
• Current mapping is maintained there.
• Preserve the wrapper contract in CLAUDEX_WRAPPER: service subcommands first otherwise source env and exec "$CLAUDE_BIN" "$@"
• Always preserve raw argument passthrough. claudex --resume must behave exactly like claude --resume with injected env.

5. Rebuild only if the deployed binary is missing or broken

• The deployed binary is: "$CLAUDEX_GATEWAY_HOME/cli-proxy-api"
• If it must be rebuilt, use the upstream repo: git clone --depth=1 https://github.com/router-for-me/CLIProxyAPI.git /tmp/CLIProxyAPI cd /tmp/CLIProxyAPI && go build -o "$CLAUDEX_GATEWAY_HOME/cli-proxy-api" ./cmd/server
• Keep the runtime config and auth directory unchanged unless the user asks otherwise.

Important Rules

• Do not “fix” the stack by replacing CLIProxyAPI with LiteLLM unless the user explicitly asks for a redesign.
• Do not silently change ports, auth file locations, or wrapper semantics.
• Do not break claudex arg passthrough.
• Prefer editing the current deployed files over creating parallel variants.
• When explaining the stack, be explicit that the working path uses chatgpt.com/backend-api/codex, not direct api.openai.com Responses calls.

Resources

scripts/

• bootstrap_stack.py: Create a new local gateway runtime on a fresh machine
• sync_codex_auth.py: Refresh the proxy auth file from ~/.codex/auth.json
• probe_stack.py: Probe health, Claude messages, tool use, and token counting
• show_status.sh: Print the current file layout, env mapping, and port status

references/

• current-stack.md: Background, file layout, commands, and troubleshooting notes