OpenClaude Advanced Setup

This guide is for users who want source builds, Bun workflows, provider profiles, diagnostics, or more control over runtime behavior.

Install Options

Option A: npm

npm install -g @gitlawb/openclaude@latest

Option B: From source with Bun

Use Bun 1.3.13 or newer for source builds on Windows. Older Bun versions can fail during bun run build.

git clone https://github.com/Gitlawb/openclaude.git
cd openclaude

bun install
bun run build
npm link

Option C: Run directly with Bun

git clone https://github.com/Gitlawb/openclaude.git
cd openclaude

bun install
bun run dev

Provider Examples

OpenAI

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o

Codex via ChatGPT auth

codexplan maps to GPT-5.5 on the Codex backend with high reasoning. codexspark maps to GPT-5.3 Codex Spark for faster loops.

If you use the in-app provider wizard, choose Codex OAuth to open ChatGPT sign-in in your browser and let OpenClaude store Codex credentials securely.

If you already use the Codex CLI, OpenClaude reads ~/.codex/auth.json automatically. You can also point it elsewhere with CODEX_AUTH_JSON_PATH or override the token directly with CODEX_API_KEY.

If you set CODEX_API_KEY manually and are not relying on auth.json or stored Codex OAuth credentials, also set CHATGPT_ACCOUNT_ID (or CODEX_ACCOUNT_ID).

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_MODEL=codexplan

# optional if you do not already have ~/.codex/auth.json
export CODEX_API_KEY=...
export CHATGPT_ACCOUNT_ID=...

openclaude

DeepSeek

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.deepseek.com/v1
export OPENAI_MODEL=deepseek-v4-flash

Use deepseek-v4-pro when you want the stronger model. deepseek-chat and deepseek-reasoner remain available as DeepSeek's legacy API aliases.

Google Gemini

export CLAUDE_CODE_USE_GEMINI=1
export GEMINI_API_KEY=...
export GEMINI_MODEL=gemini-3-flash-preview

Claude on Vertex AI

The Vertex route uses Anthropic's Claude-on-Vertex API. It is not a general Vertex AI Model Garden adapter for Gemini or arbitrary partner models; use the Gemini provider for Gemini models and OpenAI-compatible routes for compatible third-party gateways.

Authentication uses Google Application Default Credentials through google-auth-library. There is no OPENAI_API_KEY-style API key for this route. Authenticate with either a service-account file or local ADC:

gcloud auth application-default login

Minimal setup:

export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export GOOGLE_CLOUD_PROJECT=my-gcp-project
export CLOUD_ML_REGION=us-east5

openclaude --model claude-sonnet-4-6

CLOUD_ML_REGION is optional and defaults to us-east5. Model-specific Vertex region override variables are also supported for Claude models; see src/utils/envUtils.ts for the current override names.

Gemini via OpenRouter

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-or-...
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
export OPENAI_MODEL=google/gemini-2.5-pro

OpenRouter model availability changes over time. If a model stops working, try another current OpenRouter model before assuming the integration is broken.

Ollama

ollama pull llama3.3:70b

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3.3:70b

Atomic Chat (local, Apple Silicon)

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://127.0.0.1:1337/v1
export OPENAI_MODEL=your-model-name

No API key is needed for Atomic Chat local models.

Or use the profile launcher:

bun run dev:atomic-chat

Download Atomic Chat from atomic.chat. The app must be running with a model loaded before launching.

LM Studio

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:1234/v1
export OPENAI_MODEL=your-model-name

Together AI

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.together.xyz/v1
export OPENAI_MODEL=meta-llama/Llama-3.3-70B-Instruct-Turbo

Groq

export CLAUDE_CODE_USE_OPENAI=1
export GROQ_API_KEY=gsk_...
export OPENAI_BASE_URL=https://api.groq.com/openai/v1
export OPENAI_MODEL=llama-3.3-70b-versatile

GROQ_API_KEY matches the built-in Groq gateway preset. OPENAI_API_KEY also works as a fallback on the generic OpenAI-compatible path, but GROQ_API_KEY is the preferred variable for Groq-specific setup.

OpenCode Zen (pay-as-you-go)

export CLAUDE_CODE_USE_OPENAI=1
export OPENCODE_API_KEY=...
export OPENAI_BASE_URL=https://opencode.ai/zen/v1
export OPENAI_MODEL=gpt-5.4

openclaude

OpenCode Zen is a pay-as-you-go AI gateway with 41 models (GPT, Claude, Gemini, Qwen, MiniMax, GLM, Kimi, Grok, Big Pickle, DeepSeek, Nemotron). Uses the same OPENCODE_API_KEY as OpenCode Go. Get your key from https://opencode.ai.

OpenCode Go (subscription)

export CLAUDE_CODE_USE_OPENAI=1
export OPENCODE_API_KEY=...
export OPENAI_BASE_URL=https://opencode.ai/zen/go/v1
export OPENAI_MODEL=glm-5.1

openclaude

OpenCode Go is a $10/mo subscription for 12 open models (GLM, Kimi, DeepSeek, MiMo, MiniMax, Qwen). Uses the same OPENCODE_API_KEY as OpenCode Zen.

Gitlawb Opengateway

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=https://opengateway.gitlawb.com/v1
export OPENGATEWAY_API_KEY=ogw_live_...
export OPENAI_MODEL=mimo-v2.5-pro

The Opengateway route is the fresh-install startup default and requires an API key from https://gitlawb.com/opengateway/keys. Keep the base URL at /v1 and switch models with /model or OPENAI_MODEL. Current partner models include:

mimo-v2.5-pro
google/gemini-3.1-flash-lite-preview

Xiaomi MiMo

export CLAUDE_CODE_USE_OPENAI=1
export MIMO_API_KEY=...
export OPENAI_BASE_URL=https://api.xiaomimimo.com/v1
export OPENAI_MODEL=mimo-v2.5-pro

The /provider Xiaomi MiMo preset uses the same endpoint and stores the key as MIMO_API_KEY. OPENAI_API_KEY also works as a compatibility fallback, but MIMO_API_KEY keeps the profile tied to the MiMo route.

Mistral

export CLAUDE_CODE_USE_MISTRAL=1
export MISTRAL_API_KEY=...
export MISTRAL_MODEL=devstral-latest

Azure OpenAI

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=your-azure-key
export OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment/v1
export OPENAI_MODEL=gpt-4o

Microsoft Foundry / Azure OpenAI (resource URL + deployment)

When your endpoint is the resource base URL (not the full .../deployments/.../v1 path), set OPENAI_MODEL to the deployment name and AZURE_OPENAI_API_VERSION to your API version. The OpenAI shim builds:

{base}/openai/deployments/{OPENAI_MODEL}/chat/completions?api-version={AZURE_OPENAI_API_VERSION}

and sends the key in the api-key header for Azure hosts.

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=your-azure-key
export OPENAI_BASE_URL=https://your-resource.openai.azure.com
export OPENAI_MODEL=your-deployment-name
export AZURE_OPENAI_API_VERSION=2024-12-01-preview

If your hostname is not detected as Azure (for example some inference endpoints), force Azure URL and header behavior:

export OPENAI_AZURE_STYLE=1

The OpenClaude VS Code extension can store the key in Secret Storage and set these variables for you when you launch from the Control Center. See vscode-extension/openclaude-vscode/README.md.

Environment Variables

Variable	Required	Description
`CLAUDE_CODE_USE_OPENAI`	OpenAI-compatible only	Set to `1` to enable the OpenAI-compatible provider path
`OPENAI_API_KEY`	OpenAI-compatible cloud routes*	Your API key (`*` not needed for local models like Ollama, LM Studio, Atomic Chat, or other local OpenAI-compatible proxies)
`OPENAI_MODEL`	OpenAI-compatible only	Model name such as `gpt-4o`, `deepseek-v4-flash`, or `llama3.3:70b`
`OPENAI_BASE_URL`	No	API endpoint, defaulting to `https://api.openai.com/v1`
`OPENAI_API_BASE`	No	Compatibility alias for `OPENAI_BASE_URL`
`OPENCODE_API_KEY`	OpenCode Zen / Go	Shared API key for OpenCode Zen (pay-as-you-go) and OpenCode Go (subscription); get yours from https://opencode.ai
`MIMO_API_KEY`	Xiaomi MiMo route	Xiaomi MiMo API key for `https://api.xiaomimimo.com/v1`; mirrored into the OpenAI-compatible auth env when the MiMo route is active
`CLAUDE_CODE_USE_GEMINI`	Gemini only	Set to `1` to enable the direct Gemini provider path
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	Gemini API-key auth	Gemini API key for direct Gemini setup
`GEMINI_MODEL`	Gemini only	Model name such as `gemini-3-flash-preview` or `gemini-2.5-pro`
`GEMINI_BASE_URL`	No	Override the Gemini base URL
`CLAUDE_CODE_USE_MISTRAL`	Mistral only	Set to `1` to enable the dedicated Mistral provider path
`MISTRAL_API_KEY`	Mistral only	Mistral API key
`MISTRAL_MODEL`	Mistral only	Model name such as `devstral-latest`
`MISTRAL_BASE_URL`	No	Override the Mistral base URL
`CODEX_API_KEY`	Codex only	Codex or ChatGPT access token override
`CHATGPT_ACCOUNT_ID` / `CODEX_ACCOUNT_ID`	Codex only	Required for manual Codex env setup when the account id is not coming from `auth.json` or stored OAuth credentials
`CODEX_AUTH_JSON_PATH`	Codex only	Path to a Codex CLI `auth.json` file
`CODEX_HOME`	Codex only	Alternative Codex home directory
`OPENCLAUDE_MAX_RETRIES`	No	Maximum retry attempts for retryable API failures, capped at 100 (default: 10). Set to `0` to disable retries after the initial request. If unset, deprecated `CLAUDE_CODE_MAX_RETRIES` is still honored for compatibility.
`OPENCLAUDE_RETRY_DELAY_MS`	No	Base retry delay in milliseconds for APIs that do not send `Retry-After`; exponential backoff starts from this value, capped at 60000 (default: 500)
`OPENCLAUDE_DISABLE_CO_AUTHORED_BY`	No	Suppress the default `Co-Authored-By` trailer in generated git commits
`OPENCLAUDE_LOG_TOKEN_USAGE`	No	When truthy (e.g. `verbose`), emits one JSON line on stderr per API request with input/output/cache tokens and the resolved provider. User-facing debug output — complements the REPL display controlled by `/config showCacheStats`. Distinct from `CLAUDE_CODE_ENABLE_TOKEN_USAGE_ATTACHMENT`, which is model-facing (injects context usage info into the prompt itself). Both can run together.

Model env vars are provider-scoped: first-party Anthropic sessions read ANTHROPIC_MODEL, OpenAI-compatible sessions read OPENAI_MODEL, Gemini reads GEMINI_MODEL, and Mistral reads MISTRAL_MODEL. For manual Bedrock, Vertex, or Foundry launches, select the model with --model.

Runtime Hardening

Use these commands to validate your setup and catch mistakes early:

# quick startup sanity check
bun run smoke

# validate provider env + reachability
bun run doctor:runtime

# print machine-readable runtime diagnostics
bun run doctor:runtime:json

# persist a diagnostics report to reports/doctor-runtime.json
bun run doctor:report

# full local hardening check (smoke + runtime doctor)
bun run hardening:check

# strict hardening (includes project-wide typecheck)
bun run hardening:strict

Notes:

doctor:runtime fails fast if CLAUDE_CODE_USE_OPENAI=1 with a placeholder key or a missing key for non-local providers.
doctor:runtime also validates the dedicated Gemini and Mistral env paths when CLAUDE_CODE_USE_GEMINI=1 or CLAUDE_CODE_USE_MISTRAL=1.
Local providers such as http://localhost:11434/v1, http://10.0.0.1:11434/v1, and http://127.0.0.1:1337/v1 can run without OPENAI_API_KEY.
Codex profiles validate CODEX_API_KEY or the Codex CLI auth file and probe POST /responses instead of GET /models.

Provider Launch Profiles

Use profile launchers to avoid repeated environment setup:

# one-time profile bootstrap (prefer viable local Ollama, otherwise OpenAI)
bun run profile:init

# preview the best provider/model for your goal
bun run profile:recommend -- --goal coding --benchmark

# auto-apply the best available local/openai provider/model for your goal
bun run profile:auto -- --goal latency

# codex bootstrap (defaults to codexplan and ~/.codex/auth.json)
bun run profile:codex

# openai bootstrap with explicit key
bun run profile:init -- --provider openai --api-key sk-...

# gemini bootstrap with explicit key
bun run profile:init -- --provider gemini --api-key ...

# ollama bootstrap with custom model
bun run profile:init -- --provider ollama --model llama3.1:8b

# ollama bootstrap with intelligent model auto-selection
bun run profile:init -- --provider ollama --goal coding

# atomic-chat bootstrap (auto-detects running model)
bun run profile:init -- --provider atomic-chat

# codex bootstrap with a fast model alias
bun run profile:init -- --provider codex --model codexspark

# launch using persisted user-level provider profile
bun run dev:profile

# codex profile (uses CODEX_API_KEY or ~/.codex/auth.json)
bun run dev:codex

# OpenAI profile (uses the saved OpenAI profile, or OPENAI_API_KEY from your shell)
bun run dev:openai

# Gemini profile (uses the saved Gemini profile, or GEMINI_API_KEY / GOOGLE_API_KEY from your shell)
bun run dev:gemini

# Ollama profile (defaults: localhost:11434, llama3.1:8b)
bun run dev:ollama

# Atomic Chat profile (Apple Silicon local LLMs at 127.0.0.1:1337)
bun run dev:atomic-chat

profile:recommend ranks installed Ollama models for latency, balanced, or coding, and profile:auto can persist the recommendation directly.

If no profile exists yet, dev:profile uses the same goal-aware defaults when picking the initial model.

Provider Profile Model Picker Mode

When a saved provider profile is active, /model can either show the provider's catalog/discovered models or only the models explicitly listed in the profile. Configure this in ~/.openclaude.json:

{
  "providerProfileModelPickerMode": "auto"
}

Supported values:

auto (default): single-model profiles show the provider catalog; multi-model profiles show the explicit profile list; native vendor routes keep their full provider catalog.
provider: show the provider catalog/discovery list first and append profile-only custom model IDs.
profile: show only explicitly configured profile models.

Use --provider ollama when you want a local-only path. Auto mode falls back to OpenAI when no viable local chat model is installed.

Use --provider atomic-chat when you want Atomic Chat as the local Apple Silicon provider.

Use profile:codex or --provider codex when you want the ChatGPT Codex backend.

dev:openai, dev:gemini, dev:ollama, dev:atomic-chat, and dev:codex run doctor:runtime first and only launch the app if checks pass.

For dev:ollama, make sure Ollama is running locally before launch.

For dev:atomic-chat, make sure Atomic Chat is running with a model loaded before launch.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenClaude Advanced Setup

Install Options

Option A: npm

Option B: From source with Bun

Option C: Run directly with Bun

Provider Examples

OpenAI

Codex via ChatGPT auth

DeepSeek

Google Gemini

Claude on Vertex AI

Gemini via OpenRouter

Ollama

Atomic Chat (local, Apple Silicon)

LM Studio

Together AI

Groq

OpenCode Zen (pay-as-you-go)

OpenCode Go (subscription)

Gitlawb Opengateway

Xiaomi MiMo

Mistral

Azure OpenAI

Microsoft Foundry / Azure OpenAI (resource URL + deployment)

Environment Variables

Runtime Hardening

Provider Launch Profiles

Provider Profile Model Picker Mode

FilesExpand file tree

advanced-setup.md

Latest commit

History

advanced-setup.md

File metadata and controls

OpenClaude Advanced Setup

Install Options

Option A: npm

Option B: From source with Bun

Option C: Run directly with Bun

Provider Examples

OpenAI

Codex via ChatGPT auth

DeepSeek

Google Gemini

Claude on Vertex AI

Gemini via OpenRouter

Ollama

Atomic Chat (local, Apple Silicon)

LM Studio

Together AI

Groq

OpenCode Zen (pay-as-you-go)

OpenCode Go (subscription)

Gitlawb Opengateway

Xiaomi MiMo

Mistral

Azure OpenAI

Microsoft Foundry / Azure OpenAI (resource URL + deployment)

Environment Variables

Runtime Hardening

Provider Launch Profiles

Provider Profile Model Picker Mode