Connect Codex CLI to OpenLLM Buddy

Install the official Codex CLI on your machine. Use the install script (macOS/Linux), npm, or Homebrew.

1. Run one of the install commands below.
2. Confirm with codex --version.
3. Open a new terminal if codex is not found on PATH.

# macOS / Linux (official script)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Or install with npm (requires Node.js)
npm install -g @openai/codex

# Verify
codex --version

Install the scoped package @openai/codex — not unrelated npm packages named codex. Avoid sudo npm install -g; fix npm permissions instead.

Codex sends your OpenLLM Buddy API key as a Bearer token on every request. Create the key before editing config.toml.

1. Open the API keys page in the OpenLLM Buddy console.
2. Create a key and copy it immediately.
3. Ensure you have an active deployment for the model you plan to use.

You will export the key as OPENLLM_BUDDY_API_KEY in step 5. Codex reads it via the env_key field in your custom provider block.

OpenLLM Buddy exposes Chat Completions at /v1/chat/completions. In Codex, set base_url to the API root ending in /v1 — not the full chat-completions path.

https://openllmbuddy-proxy.botbuddytech.workers.dev/v1

Do notuse the built-in OpenAI provider's Responses API path for OpenLLM Buddy. Define a custom provider with wire_api = "chat" in step 4.

https://openllmbuddy-proxy.botbuddytech.workers.dev/v1/chat/completions

Also avoid nesting openai_base_url under [model_provider_config] — Codex expects it as a top-level key if you use that shortcut at all. For OpenLLM Buddy, the custom provider in step 4 is the reliable approach.

Codex reads layered config from ~/.codex/config.toml. Add a custom provider for OpenLLM Buddy that uses the Chat Completions wire API.

1. Create or open ~/.codex/config.toml.
2. Set model to your handle and model_provider to openllmbuddy.
3. Define [model_providers.openllmbuddy] with wire_api = "chat".

# ~/.codex/config.toml — OpenLLM Buddy (Chat Completions)
model = "gemma4:26b"
model_provider = "openllmbuddy"

[model_providers.openllmbuddy]
name = "OpenLLM Buddy"
base_url = "https://openllmbuddy-proxy.botbuddytech.workers.dev/v1"
env_key = "OPENLLM_BUDDY_API_KEY"
wire_api = "chat"

The provider ID openllmbuddy is arbitrary — do not use reserved IDs openai, ollama, or lmstudio. See advanced Codex configuration for profiles and managed configs.

Export OPENLLM_BUDDY_API_KEY in the same shell where you run codex. Codex loads it through the env_key you set in step 4.

1. Replace YOUR_API_KEY with your key from the console.
2. Export in your current session, or add to ~/.zshrc / ~/.bashrc.
3. Restart the terminal after editing your shell profile.

export OPENLLM_BUDDY_API_KEY="YOUR_API_KEY"

# ~/.zshrc or ~/.bashrc
export OPENLLM_BUDDY_API_KEY="YOUR_API_KEY"

You can also use codex auth for OpenAI-hosted models, but OpenLLM Buddy requires your own API key via OPENLLM_BUDDY_API_KEY.

The top-level model key in config.toml must match the handle for your OpenLLM Buddy deployment.

• Gemma 4 26B → gemma4:26b
• Qwen 3.6 27B → qwen3.6:27b

For this guide, use gemma4:26b in both config.toml and curl tests.

1. Confirm the handle on the models page.
2. Keep model and your deployed template in sync — a mismatch returns 400 or 404 from the API.

Before launching Codex, confirm your API key, Base URL, and model handle work with a direct Chat Completions request.

curl "https://openllmbuddy-proxy.botbuddytech.workers.dev/v1/chat/completions" \
  -H "Authorization: Bearer $OPENLLM_BUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma4:26b", "messages": [{"role": "user", "content": "Reply with OK"}]}'

You should receive JSON with an assistant message. 401 means a bad API key — check the console. 404 usually means base_url includes /chat/completions — revert to step 3.

With config.toml saved and OPENLLM_BUDDY_API_KEY exported, start Codex inside your project directory.

1. cd into the repo you want Codex to work on.
2. Run codex to open the TUI.
3. Ask Codex to make a small change to verify it reaches your OpenLLM Buddy endpoint.

# From your project directory
cd ~/your-repo
codex

Codex sandbox and approval settings live in the same config.toml file. Tune approval_policy and sandbox per the official docs before running on production repos.

Common Codex + OpenLLM Buddy issues and fixes.

Requests go to api.openai.com

You are still on the built-in OpenAI provider. Set model_provider to your custom block (step 4) and use wire_api = "chat".

openai_base_url ignored

Must be a top-level key in config.toml, not under [model_provider_config]. Prefer the custom provider approach for OpenLLM Buddy.

401 Unauthorized

Check OPENLLM_BUDDY_API_KEY in the shell running Codex. Rotate keys in the console if needed.

404 Not Found

Wrong base_url — use …/v1 only. Wrong wire API — OpenLLM Buddy needs wire_api = "chat", not responses.

Model errors

Align model in config with your deployed template. See step 6 and the models page.

Codex CLI is now pointed at your OpenLLM Buddy deployment. Keep your API key in env vars or a secrets manager — not in git.

• Re-run the curl test after rotating keys or changing models.
• Use Codex profiles in config.toml if you switch between OpenLLM Buddy and other providers.
• Add an AGENTS.md in repos to steer Codex behavior per project.

Browse other guides on the integrations hub. Change model context with ?model= in this page URL.

Quick reference for Codex + OpenLLM Buddy wiring.

Config file

~/.codex/config.toml

model_provider

openllmbuddy

base_url

https://openllmbuddy-proxy.botbuddytech.workers.dev/v1

wire_api

chat

env_key

OPENLLM_BUDDY_API_KEY

model

gemma4:26b

Chat Completions URL

https://openllmbuddy-proxy.botbuddytech.workers.dev/v1/chat/completions

Auth header

Authorization: Bearer YOUR_API_KEY

Notes

OpenLLM Buddy uses Chat Completions. Set wire_api = "chat" on your custom provider — not responses.