How to Configure Codex and Claude Code with a Relay API

This is a practical guide: you already have an AI relay account, and you want Codex and Claude Code to use that relay.

Keep these boundaries clear:

• Codex needs an OpenAI Responses-compatible endpoint.
• Claude Code needs an Anthropic Messages-compatible endpoint.

Prepare Three Values First

Open your relay dashboard and find:

1. OpenAI-compatible endpoint: for example https://relay.example.com/v1, used by Codex.
2. Anthropic-compatible endpoint: for example https://relay.example.com, used by Claude Code.
3. API keys and model ids: for example sk-..., gpt-5.5, or claude-sonnet-4-6. Use the exact model ids from your relay dashboard.

Pay special attention to the /v1 suffix. Many OpenAI-compatible platforms ask you to use https://relay.example.com/v1, but some platforms ask you to use only https://relay.example.com and append paths internally. Do not treat the sample as a fixed rule. Follow your relay provider’s docs first; if you are unsure, try both with a minimal smoke test.

This guide stores keys in separate user-level files:

• Codex key: ~/.codex/relay-openai.key
• Claude Code key: ~/.claude/relay-anthropic.key

That keeps secrets out of your repository and avoids asking beginners to manage shell environment variables.

Windows: Native PowerShell Setup

If you run codex and claude from Windows Terminal or PowerShell, use this section. If your project lives in WSL, skip to the WSL section.

Step 1: Check the Commands

Open PowerShell:

codex --version
claude --version

Install anything missing:

npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

Step 2: Create the Codex Key File

Codex key file path:

C:\Users\your-user\.codex\relay-openai.key

Run:

New-Item -ItemType Directory -Force "$HOME\.codex"
Set-Content -NoNewline -Path "$HOME\.codex\relay-openai.key" -Value "sk-your-relay-openai-key"

Replace sk-your-relay-openai-key with your relay OpenAI-compatible key.

Step 3: Edit the Codex Config File

Codex main config path:

C:\Users\your-user\.codex\config.toml

Open it:

notepad "$HOME\.codex\config.toml"

Paste this config. The important part is auth.command: Codex runs this command to read the token from your key file.

model = "gpt-5.5"
model_provider = "relay-openai"

[model_providers.relay-openai]
name = "Relay OpenAI"
base_url = "https://relay.example.com/v1"
wire_api = "responses"

[model_providers.relay-openai.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Get-Content -Raw $HOME/.codex/relay-openai.key"]

[profiles.relay]
model = "gpt-5.5"
model_provider = "relay-openai"
model_reasoning_effort = "medium"

Save and close Notepad.

Step 4: Create the Claude Code Key File

Claude Code key file path:

C:\Users\your-user\.claude\relay-anthropic.key

Run:

New-Item -ItemType Directory -Force "$HOME\.claude"
Set-Content -NoNewline -Path "$HOME\.claude\relay-anthropic.key" -Value "sk-your-relay-anthropic-key"

Step 5: Edit the Claude Code Settings File

Claude Code main settings path:

C:\Users\your-user\.claude\settings.json

Open it:

notepad "$HOME\.claude\settings.json"

Paste:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "apiKeyHelper": "powershell -NoProfile -Command \"Get-Content -Raw $HOME/.claude/relay-anthropic.key\"",
  "env": {
    "ANTHROPIC_BASE_URL": "https://relay.example.com",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

apiKeyHelper reads the key from the file. You do not need to set ANTHROPIC_API_KEY in PowerShell.

Step 6: Test

codex exec --profile relay "Say hello in one short sentence."
claude -p "Say hello in one short sentence."

If both commands return a short response, then start using them for code tasks.

Windows: If You Use WSL

If your repository lives in WSL, do not edit the Windows C:\Users\...\ files. Edit the Linux files inside WSL:

/home/your-linux-user/.codex/config.toml
/home/your-linux-user/.codex/relay-openai.key
/home/your-linux-user/.claude/settings.json
/home/your-linux-user/.claude/relay-anthropic.key

Enter WSL:

wsl

Confirm you are inside WSL:

echo $WSL_DISTRO_NAME

If it prints Ubuntu, Debian, or another distro name, follow the Linux section.

macOS: Terminal Setup

macOS user directories usually live under /Users/your-user.

Step 1: Check the Commands

Open Terminal:

codex --version
claude --version

Install anything missing:

npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

Step 2: Create the Codex Key File

mkdir -p ~/.codex
printf "%s" "sk-your-relay-openai-key" > ~/.codex/relay-openai.key
chmod 600 ~/.codex/relay-openai.key

Replace sk-your-relay-openai-key with your relay OpenAI-compatible key.

Step 3: Edit the Codex Config File

Codex config path:

/Users/your-user/.codex/config.toml

Open it with TextEdit:

touch ~/.codex/config.toml
open -e ~/.codex/config.toml

Or use nano:

nano ~/.codex/config.toml

Paste this config. Replace /Users/your-user/ with your real user path.

model = "gpt-5.5"
model_provider = "relay-openai"

[model_providers.relay-openai]
name = "Relay OpenAI"
base_url = "https://relay.example.com/v1"
wire_api = "responses"

[model_providers.relay-openai.auth]
command = "cat"
args = ["/Users/your-user/.codex/relay-openai.key"]

[profiles.relay]
model = "gpt-5.5"
model_provider = "relay-openai"
model_reasoning_effort = "medium"

Why not use ~ in args? Codex runs cat directly, so shell expansion does not happen. Use the absolute path.

Step 4: Create the Claude Code Key File

mkdir -p ~/.claude
printf "%s" "sk-your-relay-anthropic-key" > ~/.claude/relay-anthropic.key
chmod 600 ~/.claude/relay-anthropic.key

Step 5: Edit the Claude Code Settings File

Claude Code settings path:

/Users/your-user/.claude/settings.json

Open it:

touch ~/.claude/settings.json
open -e ~/.claude/settings.json

Paste this config. Replace /Users/your-user/ with your real user path.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "apiKeyHelper": "cat /Users/your-user/.claude/relay-anthropic.key",
  "env": {
    "ANTHROPIC_BASE_URL": "https://relay.example.com",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Step 6: Test

codex exec --profile relay "Say hello in one short sentence."
claude -p "Say hello in one short sentence."

Linux: Bash or Zsh Setup

Linux and WSL are nearly the same.

Step 1: Check the Commands

codex --version
claude --version

Install anything missing:

npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

Step 2: Create the Codex Key File

mkdir -p ~/.codex
printf "%s" "sk-your-relay-openai-key" > ~/.codex/relay-openai.key
chmod 600 ~/.codex/relay-openai.key

Step 3: Edit the Codex Config File

Linux path:

/home/your-user/.codex/config.toml

Edit it:

nano ~/.codex/config.toml

Paste this config. Replace /home/your-user/ with your real path.

model = "gpt-5.5"
model_provider = "relay-openai"

[model_providers.relay-openai]
name = "Relay OpenAI"
base_url = "https://relay.example.com/v1"
wire_api = "responses"

[model_providers.relay-openai.auth]
command = "cat"
args = ["/home/your-user/.codex/relay-openai.key"]

[profiles.relay]
model = "gpt-5.5"
model_provider = "relay-openai"
model_reasoning_effort = "medium"

Step 4: Create the Claude Code Key File

mkdir -p ~/.claude
printf "%s" "sk-your-relay-anthropic-key" > ~/.claude/relay-anthropic.key
chmod 600 ~/.claude/relay-anthropic.key

Step 5: Edit the Claude Code Settings File

Linux path:

/home/your-user/.claude/settings.json

Edit it:

nano ~/.claude/settings.json

Paste this config. Replace /home/your-user/ with your real path.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "apiKeyHelper": "cat /home/your-user/.claude/relay-anthropic.key",
  "env": {
    "ANTHROPIC_BASE_URL": "https://relay.example.com",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Step 6: Test

codex exec --profile relay "Say hello in one short sentence."
claude -p "Say hello in one short sentence."

Where Files Live

Where should each setting live?

Setting	Codex	Claude Code
Main config	~/.codex/config.toml	~/.claude/settings.json
API key file	~/.codex/relay-openai.key	~/.claude/relay-anthropic.key
Project-specific config	.codex/config.toml	.claude/settings.local.json
Team-shared rules	repository .codex/, without secrets	.claude/settings.json, without secrets

Windows mapping:

• ~/.codex/config.toml means %USERPROFILE%\.codex\config.toml in native Windows.
• ~/.claude/settings.json means %USERPROFILE%\.claude\settings.json in native Windows.
• In WSL, ~ is the Linux home directory, not the Windows home directory.

Common Failures

Codex Returns 404

Check base_url and protocol first:

wire_api = "responses"

The /v1 suffix in base_url is not universal. If your relay docs say https://relay.example.com/v1, include /v1. If the docs say https://relay.example.com, try it without /v1 first. When you see a 404, test both forms:

base_url = "https://relay.example.com/v1"

base_url = "https://relay.example.com"

Your relay must support OpenAI Responses API. A relay that only supports /v1/chat/completions may not work with Codex.

Codex Authentication Fails

First confirm the key file exists:

cat ~/.codex/relay-openai.key

If it prints the key, confirm that the args path in config.toml is absolute. macOS should look like /Users/your-user/...; Linux should look like /home/your-user/....

Claude Code Authentication Fails

First confirm that apiKeyHelper can output the key.

macOS / Linux:

cat ~/.claude/relay-anthropic.key

Windows PowerShell:

Get-Content -Raw "$HOME\.claude\relay-anthropic.key"

If it prints the key, check that ANTHROPIC_BASE_URL is an Anthropic-compatible endpoint, not an OpenAI /v1 endpoint.

Model Not Found

Dashboard display names are not always API model ids. Trust the relay docs or the /models response.

Codex model:

model = "gpt-5.5"

Claude Code model:

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Final Checklist

Check in this order:

1. codex --version and claude --version print versions.
2. Codex key file and config.toml are in the correct path.
3. Claude Code key file and settings.json are in the correct path.
4. API keys are not stored in the repository.
5. codex exec --profile relay "Say hello" returns a response.
6. claude -p "Say hello" returns a response.
7. Ask each tool to read a small file before asking it to edit code.

Agent tools can burn balance quickly once they enter multi-turn workflows. A small smoke test saves time and money.

Related Reading

• AI Relay, Official API, or Subscription: Which One Should You Use?
• Why Codex and Claude Code Need Git Branches and Pull Requests
• How to Choose a Reliable AI Relay Station

References

• OpenAI Codex Config Basics
• OpenAI Codex Configuration Reference
• OpenAI Codex Windows
• Claude Code Settings
• Claude Code Environment Variables
• Claude Code Setup