Src

Configure OpenAI Codex CLI to use Vertex AI Gemini models via LiteLLM. A guide for translating strict Codex requests for Gemini compatibility.

LiteLLM to Vertex AI Setup for Codex

This skill describes how to configure the OpenAI Codex CLI agent to communicate with Google's Vertex AI Gemini models using LiteLLM as a protocol translation proxy.

Codex requires a strict OpenAI response format and specific roles (user, assistant/model) which native Gemini or lightweight proxies (like CLIProxyAPI) do not perfectly support. LiteLLM is required to strip unsupported parameters and format the requests.

Prerequisites

• codex CLI installed (npm install -g @openai/codex)
• litellm installed and running locally
• Google Cloud Platform (GCP) Project ID with Vertex AI API enabled
• Vertex AI authentication configured (e.g., Application Default Credentials)

1. LiteLLM Configuration

You need to create a config.yaml for LiteLLM that drops complex parameters and sets content to simple strings, then routes a codex model alias to your Gemini Vertex endpoint.

Create or update your config.yaml (e.g., /app/config.yaml):

yaml

litellm_settings:
  drop_params: true
  set_content_to_str: true # Crucial for Codex: forces complex system prompts into simple strings

model_list:
  - model_name: gemini-3.1-pro-preview
    litellm_params:
      model: vertex_ai/gemini-3.1-pro-preview
      vertex_project: your-gcp-project-id
      vertex_location: global
      drop_params: true
      
  # Create aliases for Codex to use
  - model_name: codex
    litellm_params:
      model: vertex_ai/gemini-3.1-pro-preview
      vertex_project: your-gcp-project-id
      vertex_location: global
      drop_params: true

Run LiteLLM with this config (e.g., litellm --config /app/config.yaml --port 4000).

2. Codex Configuration

Codex stores its configuration in ~/.codex/config.toml. You must configure it to point to your local LiteLLM instance and specifically request the responses wire API, as Codex has deprecated the chat wire API.

Update ~/.codex/config.toml:

toml

# Use the custom LiteLLM provider
model_provider = "litellm"
# The model name here MUST match the `model_name` in your LiteLLM config
model = "gemini-3.1-pro-preview" 
model_reasoning_effort = "high"

[model_providers.litellm]
name = "litellm"
# Point to your local LiteLLM instance
base_url = "http://127.0.0.1:4000/v1"
# Crucial: Codex will error out if this is set to "chat"
wire_api = "responses" 

[projects."/path/to/your/workspace"]
trust_level = "trusted"

3. Shell Environment

Codex expects OPENAI_API_KEY to be set, even when using a custom proxy that doesn't require an actual OpenAI key.

Add this to your shell profile (~/.bashrc or ~/.zshrc):

bash

export OPENAI_API_KEY="sk-litellm"

4. Verification

To verify the setup is working, run Codex in a temporary git repository (Codex refuses to run outside a git repo):

bash

cd $(mktemp -d) && git init && codex exec 'hello'

If successful, Gemini will respond via the Codex CLI interface.

Troubleshooting

• wire_api = "chat" is no longer supported: Ensure wire_api = "responses" is set in ~/.codex/config.toml.
• Please use a valid role: user, model.: This means your proxy isn't correctly translating the OpenAI assistant or system roles to Gemini's expected format. Ensure you are using LiteLLM (not CLIProxyAPI) and that set_content_to_str: true is enabled in LiteLLM config.
• Hanging Commands / No Output: Ensure pty=true is used if calling Codex programmatically via Hermes, or that you are running it in an interactive terminal.