litellm-vertex-codex

name	litellm-vertex-codex
description	Configure OpenAI Codex CLI to use Vertex AI Gemini models via LiteLLM. A guide for translating strict Codex requests for Gemini compatibility.
version	1.0.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["Coding-Agent","Codex","Vertex-AI","Gemini","LiteLLM","Proxy"],"related_skills":["codex","claude-code"]}}

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):

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:

# 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):

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):

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.