Code CLI Any LLM

> A unified gateway for the Gemini, opencode, crush, and Qwen Code AI CLIs

For the Chinese version of this document, see README_CN.md.

🎯 Project Overview

Code CLI Any LLM (CAL) acts as a universal proxy that can masquerade as the Gemini, opencode, or crush CLI while sending traffic to any OpenAI-compatible backend (Claude Code, Codex, OpenAI, ZhipuAI, Qwen, and more). You keep the same CLI UX you already know and gain the flexibility to switch providers or spread requests across several vendors with consistent tooling.

Core Features
- 🔄 Multi-facade gateway – keep the default Gemini experience or switch to gemini/opencode/crush/qwencode via --cli-mode
- 🔌 Provider agnostic – proxy to Claude Code, Codex, OpenAI, ZhipuAI, Qwen, or any OpenAI-compatible service
- ⚡ Streaming & tools – preserve SSE streaming, tool-calling, and reasoning outputs for each CLI experience
- 🧩 Automatic configuration – generate/merge CLI config files (~/.config/opencode, ~/.config/crush, and ~/.qwen/settings.json + ~/.qwen/.env), refresh gateway.apiMode/cliMode, and restart the gateway for you
- 🛡️ Operational helpers – built-in restart/kill utilities, health reporting, and PID auto-recovery

🚀 Quick Start

$3

1. (Optional) Install the Gemini CLI if you plan to use the Gemini AI Code CLI tool:
``bash
npm install -g @google/gemini-cli@latest --registry https://registry.npmmirror.com
npm install -g @google/gemini-cli-core@latest --registry https://registry.npmmirror.com
`

2. (Optional) Install additional AI Code CLI tools if you want to try opencode, crush, or Qwen Code:
`bash
# opencode
npm install -g opencode-ai@latest

# crush
brew install charmbracelet/tap/crush # or follow the official crush installation guide

# qwen-code
npm install -g @qwen-code/qwen-code@latest
`

3. Install the CAL gateway:
`bash
npm install -g @kdump/code-cli-any-llm@latest --registry https://registry.npmmirror.com
`

$3

Launch CAL with your preferred CLI facade:

`bash
cal code --cli-mode opencode


cal code --cli-mode crush

cal code --cli-mode qwencode

cal code # defaults to the Gemini CLI experience

`

First-run wizard
- Collects the primary provider (claudeCode, codex, or openai) and connection settings:
- Base URL (pre-filled, editable)
- Default model
- Authentication mode (Codex supports ApiKey and ChatGPT)
- API key (when required by the provider)
- Automatically generates CLI config files for opencode/crush/qwencode on first use (~/.config/opencode/opencode.json, ~/.config/crush/crush.json, and ~/.qwen/settings.json + ~/.qwen/.env)
- Saves the new configuration, restarts the gateway (cal restart), and waits for the health check to pass
- When gateway.apiKey is missing in qwencode mode, CAL writes a placeholder into ~/.qwen/.env and prompts you to fill in a real key so the Qwen Code CLI can connect successfully
- Finally launches the selected AI Code CLI (Gemini by default; switch with --cli-mode at any time)

💡 Codex ChatGPT mode: Choosing Codex + ChatGPT prompts the CLI to open a browser-based OAuth login on the first request. The login URL appears in your terminal, and successful authentication writes auth.json to ~/.code-cli-any-llm/codex/. Tokens refresh automatically, so repeat logins are not required.

$3

Run this command whenever you need to update credentials or switch providers:

`bash
cal auth
`

💡 Shortcut Tip: During the configuration wizard, press Shift+Alt+. to automatically fill in the default value for any field:
- On Linux/Windows: produces >
- On macOS: produces ≥ (using Shift+Option+.)

This saves time when you want to quickly accept the suggested defaults without typing them out.

💡 Usage Examples

$3

`bash


Start a conversation

cal code "Write an HTTP service in TypeScript"

Explain code

cal code "Explain what this code does"

Optimization tips

cal code "Help me optimize this algorithm"
`

$3

`bash


Analyze the current project structure

cal code "Please analyze the architecture of this project"

Request a code review

cal code "Please review my code and suggest improvements"
`

$3

`bash


Show all Gemini CLI options

cal code --help

Use additional Gemini CLI parameters

cal code --temperature 0.7 "Write a creative story"

Launch alternate CLI experiences

cal code --cli-mode opencode
cal code --cli-mode crush
cal code --cli-mode qwencode
`

📖 User Guide

$3

cal provides the following primary commands:

- cal code [prompt] – Chat with the AI assistant (main entry point)
- cal auth – Configure AI service credentials
- cal start – Manually start the background gateway service
- cal stop – Stop the gateway service
- cal restart – Restart the gateway service
- cal status – Check the gateway status
- cal kill – Force-terminate stuck processes (troubleshooting)
- cal update – Check for updates and install the latest version
- cal version – Display the current CAL version
- cal --help – Show CLI help information

$3

1. Run cal auth, select Codex, and choose the ChatGPT authentication mode.
2. The next time you run cal code or cal start, the terminal prints an OAuth link (e.g., https://auth.openai.com/oauth/authorize?...). Open the link in a browser to complete the login.
3. During login the CLI spins up a temporary callback service on 127.0.0.1:1455. If the port is in use, free it or retry; the CLI automatically retries and explains failures.
4. After successful authorization you’ll see “Login successful, you may return to the terminal.” Tokens are stored in ~/.code-cli-any-llm/codex/auth.json.
5. Tokens refresh automatically. Deleting auth.json triggers a fresh browser login on the next request.

Set CODEX_HOME to change where OAuth tokens are stored (default ~/.code-cli-any-llm/codex).

$3

CAL merges configuration from three layers (higher priority overrides lower priority):

1. Project configuration – ./config/config.yaml
2. Global configuration – ~/.code-cli-any-llm/config.yaml
3. Environment variables – baseline defaults

$3

- gateway.apiMode: determines which API surface the gateway exposes (gemini or openai). Set to openai to enable /api/v1/openai/v1/... endpoints.
- gateway.cliMode: sets the default CLI launched by cal code (gemini, opencode, crush, or qwencode). Override per run with --cli-mode.
- gateway.apiKey: optional shared key forwarded to OpenAI-compatible CLIs. Use it in opencode/crush configs or via environment variables such as CODE_CLI_API_KEY.

When gateway.apiMode is openai, the gateway exposes:
- GET /api/v1/openai/v1/models
- POST /api/v1/openai/v1/chat/completions
- POST /api/v1/openai/v1/responses

$3

| Provider | Base URL | Recommended models |
| --- | --- | --- |
| Codex | https://chatgpt.com/backend-api/codex | gpt-5-codex |
| Claude Code | https://open.bigmodel.cn/api/anthropic
(or a relay endpoint such as https:///api) | claude-sonnet-4-5-20250929, claude-3.5-sonnet-20241022 |
| ZhipuAI (default) | https://open.bigmodel.cn/api/paas/v4 | glm-4.5 |
| OpenAI | https://api.openai.com/v1 | gpt-4, gpt-4o |
| Qwen | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-plus, qwen-turbo |
| Other OpenAI-compatible services | Custom URL | Model name provided by the vendor |

$3

Baseline settings can be provided through environment variables. Examples:

`bash


Primary provider (claudeCode / codex / openai)

export CAL_AI_PROVIDER="codex"

Codex configuration

export CAL_CODEX_AUTH_MODE="chatgpt" # apikey or chatgpt (default apikey)
export CAL_CODEX_API_KEY="your-codex-api-key" # only required for ApiKey mode
export CAL_CODEX_BASE_URL="https://chatgpt.com/backend-api/codex"
export CAL_CODEX_MODEL="gpt-5-codex"
export CAL_CODEX_TIMEOUT="1800000"
export CAL_CODEX_REASONING='{"effort":"medium"}'
export CAL_CODEX_TEXT_VERBOSITY="medium"
export CODEX_HOME="$HOME/.custom-codex" # optional OAuth token directory

Claude Code configuration

export CAL_CLAUDE_CODE_API_KEY="your-claude-code-api-key"
export CAL_CLAUDE_CODE_BASE_URL="https://open.bigmodel.cn/api/anthropic"
export CAL_CLAUDE_CODE_MODEL="claude-sonnet-4-5-20250929"
export CAL_CLAUDE_CODE_TIMEOUT="1800000"
export CAL_CLAUDE_CODE_VERSION="2023-06-01"
export CAL_CLAUDE_CODE_BETA="claude-code-20250219,interleaved-thinking-2025-05-14"
export CAL_CLAUDE_CODE_USER_AGENT="claude-cli/1.0.119 (external, cli)"
export CAL_CLAUDE_CODE_X_APP="cli"
export CAL_CLAUDE_CODE_DANGEROUS_DIRECT="true"
export CAL_CLAUDE_CODE_MAX_OUTPUT="64000"

OpenAI / compatible providers

export CAL_OPENAI_API_KEY="your-api-key"
export CAL_OPENAI_BASE_URL="https://api.openai.com/v1"
export CAL_OPENAI_MODEL="gpt-4"
export CAL_OPENAI_TIMEOUT="1800000"
export CAL_OPENAI_ORGANIZATION="org-xxxxxx" # optional organization ID

Gateway configuration

export CAL_PORT="23062"
export CAL_HOST="0.0.0.0"
export CAL_LOG_LEVEL="info"
export CAL_GATEWAY_LOG_DIR="$HOME/.code-cli-any-llm/logs"
export CAL_GATEWAY_API_MODE="openai"
export CAL_GATEWAY_CLI_MODE="opencode"
export CAL_GATEWAY_API_KEY="shared-demo-key"
export CAL_DISABLE_UPDATE_CHECK="1" # disable automatic update prompts

Advanced controls

export CAL_RATE_LIMIT_MAX="100" # per-15-minute rate limit cap
export CAL_REQUEST_TIMEOUT="3600000" # request timeout in milliseconds
export CAL_ALLOWED_ORIGINS="http://localhost:3000,http://localhost:8080"
export CAL_LOG_DIR="/custom/log/path" # custom log directory
`

$3

For project-specific defaults, create config/config.yaml in your project root:

`yaml
openai:
apiKey: "project-specific-key"
model: "gpt-4"
baseURL: "https://api.openai.com/v1"
timeout: 1800000
gateway:
port: 23062
host: "0.0.0.0"
logLevel: "info"
logDir: "./logs"
`

To make Codex the default provider for a project:

`yaml
aiProvider: codex
codex:
authMode: ApiKey
apiKey: "project-codex-key"
baseURL: "https://chatgpt.com/backend-api/codex"
model: "gpt-5-codex"
timeout: 1800000
reasoning:
effort: medium
textVerbosity: medium
`

For OAuth mode:

`yaml
aiProvider: codex
codex:
authMode: ChatGPT
baseURL: "https://chatgpt.com/backend-api/codex"
model: "gpt-5-codex"
timeout: 1800000
reasoning:
effort: medium
summary: auto
textVerbosity: medium
`

🔧 Detailed Configuration

$3

- aiProvider – primary provider (openai, codex, or claudeCode)
- codex.authMode – ApiKey (static key) or ChatGPT (OAuth login with automatic refresh)
- openai.apiKey – API key for OpenAI or compatible services
- openai.baseURL – OpenAI-compatible endpoint URL
- openai.model – default model name (default glm-4.5)
- openai.timeout – request timeout in milliseconds (default 1,800,000 ≈ 30 minutes)
- codex.apiKey – Codex API key (required in ApiKey mode)
- codex.baseURL – Codex endpoint URL (default https://chatgpt.com/backend-api/codex)
- codex.model – Codex model name (default gpt-5-codex)
- codex.timeout – Codex timeout in milliseconds (default 1,800,000)
- codex.reasoning – reasoning configuration following the Codex Responses API schema
- codex.textVerbosity – verbosity level: low, medium, or high

$3

- gateway.port – service port (default 23062)
- gateway.host – bind address (default 0.0.0.0)
- gateway.logLevel – log level (debug, info, warn, error)
- gateway.logDir – log directory (default ~/.code-cli-any-llm/logs)

🛠️ Troubleshooting

$3

Symptom: cal code hangs or prints no output.

Solution:
`bash
cal kill # clean up stuck processes
cal code "Hello" # retry the conversation
`

$3

Symptom: API key rejected or authentication errors.

Solution:
`bash
cal auth # rerun the configuration wizard
`

Checklist
- Confirm the API key is correct and active
- Ensure the base URL matches the provider
- Verify the account has sufficient quota

$3

Symptom: gateway fails to boot or health check reports errors.

Solution:
`bash
cal status # inspect current gateway health
cal restart # restart the service
cal kill && cal start # force cleanup if the problem persists
`

Checklist
- Test network connectivity to the AI provider
- Ensure port 23062 is free
- Verify the configuration file format

$3

Symptom: port 23062 is already in use.

Solution:
1. Change the port in the configuration file:
`yaml
# ~/.code-cli-any-llm/config.yaml
gateway:
port: 23063
`
2. Or set it via environment variables:
`bash
export PORT=23063
`

$3

Symptom: configuration validation fails.

Solution
1. Check the syntax in ~/.code-cli-any-llm/config.yaml
2. Ensure all required fields are present
3. Validate file permissions (chmod 600)

$3

Symptom: unable to read or write configuration files.

Solution:
`bash
chmod 700 ~/.code-cli-any-llm
chmod 600 ~/.code-cli-any-llm/config.yaml
`

$3

Symptom: requests time out or the provider is unreachable.

Solution
1. Check your network connection
2. Try an alternate baseURL (for example, a local relay)
3. Increase the timeout:
`yaml
openai:
timeout: 1800000
`

$3

Inspect detailed logs when diagnosing issues:

`bash
tail -n 300 -f ~/.code-cli-any-llm/logs/gateway-*.log

export LOG_LEVEL=debug
cal restart
`

❓ FAQ

$3

Symptom
- Gemini CLI reports “Model stream ended with an invalid chunk or missing finish reason.”
- Gateway logs contain InternalError.Algo.InvalidParameter: Range of input length should be [1, 98304].

Cause: the prompt or file exceeds the model’s default token limit.

Solution
1. Increase the maximum input tokens via extraBody.max_input_tokens:
`yaml
# ~/.code-cli-any-llm/config.yaml
openai:
apiKey: "your-api-key"
baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
model: "qwen-plus-latest"
extraBody:
max_input_tokens: 200000
`
2. Review the vendor’s documentation for exact limits (for example, some Qwen models allow up to 1,000,000 tokens).

$3

Run the wizard again:
`bash
cal auth
`

Select the provider you need, or set CAL_AI_PROVIDER before running the wizard.

$3

Create config/config.yaml in the project root:
`yaml
openai:
apiKey: "project-key"
model: "gpt-4"
baseURL: "https://api.openai.com/v1"
timeout: 1800000
gateway:
logLevel: "debug"
`

Project-level configuration has the highest priority.

$3

1. Check the gateway status with cal status.
2. Verify connectivity to the provider.
3. Increase the timeout if needed.
4. Restart the service with cal restart.

📚 More Resources

- 📋 Development Guide – Environment setup and build instructions
- 🧠 Architecture Guide – Technical architecture and design notes
- 🧪 Testing Guide – Testing strategy and instructions

$3

- Interactive cal commands check ~/.code-cli-any-llm/version.json and refresh the cache every 20 hours. Network issues never block execution.
- When cal code detects a newer version, the prompt offers y (update now), n (skip), skip (ignore this release), or off (disable future checks and restart the gateway).
- Run cal update at any time to synchronously refresh and install the latest package.
- Set CAL_DISABLE_UPDATE_CHECK=1 or choose off` in the prompt to opt out permanently.

🙏 Acknowledgements

CAL draws inspiration from claude-code-router, llxprt-code, and aio-cli. Huge thanks to these outstanding open-source projects and their contributors.

🤝 Contributing

Issues and pull requests are welcome!

📄 License

Apache License 2.0

Qwen Code config directory override (optional, defaults to ~/.qwen)

export CAL_QWEN_HOME="$HOME/.qwen"