codex-shim-byok-models

Q: How do I install codex-shim-byok-models?

Run npx skills add https://github.com/reason-machines/codex-skills --skill codex-shim-byok-models in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/codex-shim-byok-models/ (personal) or .claude/skills/codex-shim-byok-models/ (project).

by reason-machinesBackend & APIs

Run Codex Desktop with Factory BYOK models and ChatGPT GPT-5.5 via local API shim

Installs: 231
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/codex-skills --skill codex-shim-byok-models

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads codex-shim-byok-models automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Codex Shim BYOK Models

Skill by ara.so — Codex Skills collection.

Overview

codex-shim is a local Python API shim that intercepts Codex Desktop's model requests and routes them to:

Any model in your ~/.factory/settings.json (Factory BYOK)
Your ChatGPT subscription GPT-5.5
Custom OpenAI/Anthropic/generic chat completion endpoints

It exposes a local Responses API endpoint that Codex Desktop points to, bypassing Codex's server-side Statsig model allowlist.

Key capabilities:

Use any OpenAI, Anthropic, DeepSeek, Gemini, OpenRouter, or Z.ai model
Keep ChatGPT subscription GPT-5.5 alongside BYOK models
No modification to ~/.codex/config.toml (uses launch-time overrides)
Translates between Codex Responses API ↔ upstream APIs (OpenAI chat completions, Anthropic messages)

Installation

# Clone repository
git clone https://github.com/0xSero/codex-shim ~/Documents/codex-shim
cd ~/Documents/codex-shim

# Install Python dependencies (requires 3.11+)
python3 -m pip install --user aiohttp pytest

# Symlink commands to PATH
ln -s "$PWD/bin/codex-shim" ~/.local/bin/codex-shim
ln -s "$PWD/bin/codex-app"  ~/.local/bin/codex-app
ln -s "$PWD/bin/codex-model" ~/.local/bin/codex-model

Verify installation:

codex-shim --help

Configuration

Factory Settings File

The shim reads ~/.factory/settings.json by default. Structure:

{
  "customModels": [
    {
      "model": "gpt-5.5",
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${OPENAI_API_KEY}",
      "displayName": "OpenAI GPT-5.5",
      "maxContextLimit": 400000
    },
    {
      "model": "claude-opus-4-7-20251109",
      "provider": "anthropic",
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "displayName": "Claude Opus 4.7"
    },
    {
      "model": "deepseek-v4-pro",
      "provider": "anthropic",
      "baseUrl": "https://api.deepseek.com/anthropic",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "displayName": "DeepSeek V4 Pro",
      "noImageSupport": true
    }
  ]
}

Supported providers:

openai → OpenAI /v1/chat/completions
generic-chat-completion-api → OpenAI-compatible endpoints
anthropic → Anthropic /v1/messages

Custom Config Path

codex-shim --settings /path/to/custom-models.json generate
codex-shim --settings /path/to/custom-models.json start

Environment Variables

Store API keys in environment:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export DEEPSEEK_API_KEY="..."

Key Commands

Generate Catalog

Reads Factory settings and creates .codex-shim/custom_model_catalog.json:

codex-shim generate

Start/Stop Daemon

# Start shim on 127.0.0.1:8765
codex-shim start

# Check status
codex-shim status

# Stop daemon
codex-shim stop

# Restart
codex-shim restart

List Available Models

# Show all generated slugs and upstream routes
codex-shim list

# Show models currently in Codex Desktop picker
codex-model list

Launch Codex Desktop

# Launch with shim wired in (doesn't modify ~/.codex/config.toml)
codex-app

# Launch and open specific path
codex-app /path/to/project

# Equivalent long form
codex-shim app /path/to/project

Switch Active Model

# List available slugs
codex-model list

# Set default model for next launch
codex-model openai-gpt-5-5

# Relaunch Codex
codex-app

Run Codex CLI Through Shim

codex-shim codex -- chat "explain this code"
codex-shim codex -- edit main.py "add error handling"

Model Routing Architecture

Codex Desktop → /v1/responses → codex-shim (127.0.0.1:8765)
                                   ┃
                    ┏━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━┓
                    ┃              ┃              ┃
         slug "openai-gpt-5-5"    provider       provider
                    ┃            "openai"      "anthropic"
                    ┃              ┃              ┃
         chatgpt.com/backend-api  baseUrl/       baseUrl/
         /codex/responses         chat/          messages
         (Bearer token)           completions    (x-api-key)

The shim:

Receives Codex Responses API request
Looks up slug in catalog
Translates to upstream format (OpenAI chat completions or Anthropic messages)
Streams upstream response
Translates back to Responses API format

Code Examples

Python: Implementing Custom Provider Translation

# codex_shim/translator.py example pattern

async def translate_to_openai(responses_request):
    """Convert Codex Responses API → OpenAI chat completions."""
    return {
        "model": responses_request["model"],
        "messages": responses_request["messages"],
        "stream": True,
        "temperature": responses_request.get("temperature", 1.0),
        "max_tokens": responses_request.get("max_tokens"),
    }

async def translate_to_anthropic(responses_request):
    """Convert Codex Responses API → Anthropic messages."""
    messages = []
    system = None
    
    for msg in responses_request["messages"]:
        if msg["role"] == "system":
            system = msg["content"]
        else:
            messages.append({
                "role": msg["role"],
                "content": msg["content"]
            })
    
    body = {
        "model": responses_request["model"],
        "messages": messages,
        "stream": True,
        "max_tokens": responses_request.get("max_tokens", 4096),
    }
    
    if system:
        body["system"] = system
    
    return body

Python: Adding Custom Model Programmatically

import json
from pathlib import Path

def add_custom_model(model_config):
    """Add model to Factory settings."""
    settings_path = Path.home() / ".factory" / "settings.json"
    
    if settings_path.exists():
        with open(settings_path) as f:
            settings = json.load(f)
    else:
        settings = {"customModels": []}
    
    settings["customModels"].append(model_config)
    
    with open(settings_path, "w") as f:
        json.dump(settings, f, indent=2)

# Example: Add OpenRouter model
add_custom_model({
    "model": "anthropic/claude-3.5-sonnet",
    "provider": "openai",
    "baseUrl": "https://openrouter.ai/api/v1",
    "apiKey": "${OPENROUTER_API_KEY}",
    "displayName": "Claude 3.5 Sonnet (OpenRouter)",
    "maxContextLimit": 200000
})

Shell: Automated Setup Script

#!/bin/bash
# setup-codex-shim.sh

set -e

CODEX_SHIM_DIR="$HOME/Documents/codex-shim"

# Clone and install
if [ ! -d "$CODEX_SHIM_DIR" ]; then
    git clone https://github.com/0xSero/codex-shim "$CODEX_SHIM_DIR"
fi

cd "$CODEX_SHIM_DIR"
python3 -m pip install --user aiohttp

# Symlink commands
mkdir -p "$HOME/.local/bin"
ln -sf "$CODEX_SHIM_DIR/bin/codex-shim" "$HOME/.local/bin/"
ln -sf "$CODEX_SHIM_DIR/bin/codex-app" "$HOME/.local/bin/"
ln -sf "$CODEX_SHIM_DIR/bin/codex-model" "$HOME/.local/bin/"

# Generate catalog and start
codex-shim generate
codex-shim start

echo "✓ Shim installed and running"
codex-shim status

macOS Picker Patch

Codex Desktop's Statsig config hides models not on a server-side allowlist. Apply this one-time ASAR patch to bypass:

APP=/Applications/Codex.app

# Backup
sudo cp -R "$APP" "$APP.unpatched-$(date +%Y%m%d-%H%M%S)"

# Extract ASAR
cd /tmp && rm -rf codex-asar-patch && mkdir codex-asar-patch && cd codex-asar-patch
npx --yes @electron/asar extract "$APP/Contents/Resources/app.asar" extracted

# Patch picker filter (disables useHiddenModels check)
PATCH_FILE=$(grep -RIl 'useHiddenModels' extracted/webview/assets/model-queries-*.js | head -n1)
sed -i.bak -E 's/let u=c\.useHiddenModels&&o!==`amazonBedrock`,d;/let u=!1,d;/' "$PATCH_FILE"

# Verify exactly one change
diff "$PATCH_FILE.bak" "$PATCH_FILE" && echo "ERROR: No changes made" && exit 1
rm "$PATCH_FILE.bak"

# Repack
npx --yes @electron/asar pack extracted app.asar.new
sudo cp app.asar.new "$APP/Contents/Resources/app.asar"

# Recompute ASAR header hash for Electron integrity check
HEADER_HASH=$(python3 - "$APP/Contents/Resources/app.asar" <<'PY'
import struct, hashlib, sys
with open(sys.argv[1], 'rb') as f:
    data_size, header_size, _, json_size = struct.unpack('<4I', f.read(16))
    header_json = f.read(json_size)
print(hashlib.sha256(header_json).hexdigest())
PY
)

# Update Info.plist
sudo /usr/libexec/PlistBuddy -c \
  "Set :ElectronAsarIntegrity:Resources/app.asar:hash $HEADER_HASH" \
  "$APP/Contents/Info.plist"

# Re-sign (ad-hoc)
sudo codesign --force --deep --sign - "$APP"

echo "✓ Patch applied. Launch Codex Desktop."

Rollback:

sudo rm -rf "$APP"
sudo mv "$APP.unpatched-YYYYMMDD-HHMMSS" "$APP"

ChatGPT GPT-5.5 Passthrough

If ~/.codex/auth.json exists with auth_mode: chatgpt, the shim auto-generates a synthetic slug openai-gpt-5-5 that proxies to:

https://chatgpt.com/backend-api/codex/responses
Authorization: Bearer <access_token from auth.json>

This bypasses Factory and uses your ChatGPT subscription quota.

Disable:

# Remove from catalog after generation
jq 'del(.models[] | select(.slug == "openai-gpt-5-5"))' \
  .codex-shim/custom_model_catalog.json > tmp.json && mv tmp.json .codex-shim/custom_model_catalog.json

Common Patterns

Multi-Provider Setup

{
  "customModels": [
    {
      "model": "gpt-5.5",
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${OPENAI_API_KEY}",
      "displayName": "GPT-5.5"
    },
    {
      "model": "claude-opus-4-7-20251109",
      "provider": "anthropic",
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "displayName": "Claude Opus 4.7"
    },
    {
      "model": "gemini-2.0-flash-exp",
      "provider": "openai",
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
      "apiKey": "${GOOGLE_API_KEY}",
      "displayName": "Gemini 2.0 Flash"
    }
  ]
}

OpenRouter Aggregation

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "provider": "openai",
  "baseUrl": "https://openrouter.ai/api/v1",
  "apiKey": "${OPENROUTER_API_KEY}",
  "displayName": "Llama 3.3 70B (OpenRouter)"
}

DeepSeek with Anthropic-Style Thinking

{
  "model": "deepseek-v4-pro",
  "provider": "anthropic",
  "baseUrl": "https://api.deepseek.com/anthropic",
  "apiKey": "${DEEPSEEK_API_KEY}",
  "displayName": "DeepSeek V4 Pro",
  "noImageSupport": true
}

The shim translates extended thinking blocks from thinking items to reasoning.encrypted_content.

Troubleshooting

Models Don't Appear in Picker

Cause: Statsig allowlist still active.

Solution: Apply macOS picker patch (see section above).

"Connection refused" When Launching Codex

Cause: Shim daemon not running.

codex-shim status  # Check if running
codex-shim start   # Start if stopped

401 Unauthorized Errors

Cause: API key not found or invalid.

Check environment variables:

echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

Verify settings file:

cat ~/.factory/settings.json | jq '.customModels[].apiKey'

Test upstream directly:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

ChatGPT Passthrough Not Working

Verify auth.json exists:

cat ~/.codex/auth.json | jq '.auth_mode'
# Should output: "chatgpt"

Check access token validity:

TOKEN=$(jq -r '.access_token' ~/.codex/auth.json)
curl https://chatgpt.com/backend-api/me \
  -H "Authorization: Bearer $TOKEN"

Shim Logs

# Tail daemon logs
tail -f ~/.codex-shim/codex-shim.log

# Check last 50 lines
tail -n 50 ~/.codex-shim/codex-shim.log

Port Already in Use

# Change default port (8765)
codex-shim --port 9876 start
codex-shim --port 9876 app

Extended Thinking Not Appearing

For Anthropic-shaped providers (Claude, DeepSeek), thinking blocks appear as reasoning.encrypted_content items in Codex UI.

Verify provider is set to anthropic:

jq '.customModels[] | select(.model=="deepseek-v4-pro") | .provider' \
  ~/.factory/settings.json

Should return "anthropic", not "openai".

Testing

Run test suite:

cd ~/Documents/codex-shim
python3 -m pytest tests/ -v

Test specific translation:

# tests/test_translation.py
import pytest
from codex_shim.translator import translate_to_anthropic

@pytest.mark.asyncio
async def test_system_message_extraction():
    request = {
        "model": "claude-opus-4-7",
        "messages": [
            {"role": "system", "content": "You are helpful"},
            {"role": "user", "content": "Hello"}
        ]
    }
    
    result = await translate_to_anthropic(request)
    assert result["system"] == "You are helpful"
    assert len(result["messages"]) == 1

MCP Tool Forwarding

Codex Desktop forwards three generic MCP tools to all models (built-in and shim-routed):

list_mcp_resources
list_mcp_resource_templates
read_mcp_resource

These are available in the function calling schema for every routed model. The model calls list_mcp_resources to discover available resources.

Note: Codex Desktop does not flatten individual MCP server tools. That's a Codex client behavior, not a shim limitation.

Official Repository: https://github.com/0xSero/codex-shim
License: MIT
Requires: Python 3.11+, aiohttp

FAQ

What does the codex-shim-byok-models skill do?

Run Codex Desktop with Factory BYOK models and ChatGPT GPT-5.5 via local API shim

How do I install codex-shim-byok-models?

Run npx skills add https://github.com/reason-machines/codex-skills --skill codex-shim-byok-models in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/codex-shim-byok-models/ (personal) or .claude/skills/codex-shim-byok-models/ (project).

Which AI agents can use codex-shim-byok-models?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is codex-shim-byok-models safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains codex-shim-byok-models?

It is published by reason-machines in reason-machines/codex-skills. It has 231 recorded installs.

Popular backend & apis skills

View category →

find-skills

vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

OfficialBackend & APIs4.1M installs

entra-app-registration

microsoft/azure-skills

Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.

OfficialBackend & APIs566.7K installs

google-agents-cli-adk-code

google/agents-cli

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

entra-agent-id

microsoft/azure-skills

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).

OfficialBackend & APIs336.6K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs

codex-shim-byok-models

Install

Install

Describe the task

Review the result

SKILL.md

Codex Shim BYOK Models

Overview

Installation

Configuration

Factory Settings File

Custom Config Path

Environment Variables

Key Commands

Generate Catalog

Start/Stop Daemon

List Available Models

Launch Codex Desktop

Switch Active Model

Run Codex CLI Through Shim

Model Routing Architecture

Code Examples

Python: Implementing Custom Provider Translation

Python: Adding Custom Model Programmatically

Shell: Automated Setup Script

macOS Picker Patch

ChatGPT GPT-5.5 Passthrough

Common Patterns

Multi-Provider Setup

OpenRouter Aggregation

DeepSeek with Anthropic-Style Thinking

Troubleshooting

Models Don't Appear in Picker

"Connection refused" When Launching Codex

401 Unauthorized Errors

ChatGPT Passthrough Not Working

Shim Logs

Port Already in Use

Extended Thinking Not Appearing

Testing

MCP Tool Forwarding

FAQ

More from reason-machines/codex-skills

Popular backend & apis skills