Using Kimi in Codex

Codex is OpenAI's coding agent. The Kimi Code server natively supports the OpenAI Responses API (streaming and non-streaming, reasoning, and function calling all work), so Codex CLI and the Codex desktop app can connect directly with a custom model provider — no local routing or protocol-translation tool is needed. This guide covers the configuration.

The OpenAI Responses API supports text and image input, but not video input. To analyze video, extract key frames with ffmpeg first.

Membership

Before configuring, check your membership tier and pick a model from the table below:

Tier	Available models	Context window
Andante	kimi-for-coding	256K
Moderato	k3 k3-256k kimi-for-coding	All 256K
Allegretto and above	k3 k3-256k kimi-for-coding kimi-for-coding-highspeed	k3: up to 1M k3-256k: 256K kimi-for-coding: 256K kimi-for-coding-highspeed: 256K

New model recommendation

k3-256k is newly available. It matches k3 in quality within 256K context, while k3 (1M) consumes about twice the quota of k3-256k. k3-256k fits everyday Q&A, code completion, regular feature development, and single-file or small-scale changes. If you switch from k3 (1M) to k3-256k, compress the context first.

Prerequisites

1. Create and save an API Key in the Kimi Code Console.
2. Install Codex CLI:

npm install -g @openai/codex

Step 1: Create the model catalog models.json

Create models.json in the Codex config directory:

macOS / Linux

~/.codex/models.json

Windows

C:\Users\<username>\.codex\models.json

Write the following content (K3 series models shown as an example):

{
  "models": [
    {
      "slug": "k3",
      "display_name": "Kimi K3",
      "description": "Kimi K3, 1M context",
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        { "effort": "low", "description": "Light reasoning" },
        { "effort": "high", "description": "Enhanced reasoning" },
        { "effort": "max", "description": "Deep reasoning" }
      ],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 0,
      "base_instructions": "",
      "supports_reasoning_summaries": true,
      "default_reasoning_summary": "none",
      "support_verbosity": false,
      "truncation_policy": { "mode": "bytes", "limit": 10000 },
      "context_window": 1048576,
      "max_context_window": 1048576,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": true,
      "experimental_supported_tools": [],
      "input_modalities": ["text", "image"]
    },
    {
      "slug": "k3-256k",
      "display_name": "Kimi K3 256K",
      "description": "Kimi K3 256K context",
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        { "effort": "low", "description": "Light reasoning" },
        { "effort": "high", "description": "Enhanced reasoning" },
        { "effort": "max", "description": "Deep reasoning" }
      ],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 1,
      "base_instructions": "",
      "supports_reasoning_summaries": true,
      "default_reasoning_summary": "none",
      "support_verbosity": false,
      "truncation_policy": { "mode": "bytes", "limit": 10000 },
      "context_window": 262144,
      "max_context_window": 262144,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": true,
      "experimental_supported_tools": [],
      "input_modalities": ["text", "image"]
    }
  ]
}

Step 2: Write config.toml

Path of the Codex CLI config file:

macOS / Linux

~/.codex/config.toml

Windows

C:\Users\<username>\.codex\config.toml

Write the following content (create the file if it does not exist):

model = "k3-256k"
model_provider = "kimi"
web_search = "live"
model_catalog_json = "~/.codex/models.json"

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.kimi.com/coding/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"

[desktop]
enabled-reasoning-efforts = ["low", "high", "max"]

Field reference:

Field	Description
model	Default model. k3-256k is recommended (more quota-friendly); use k3 when you need the 1M context window
model_provider	Default provider, matching the [model_providers.kimi] table below
web_search	Web search switch. The Kimi Code endpoint supports web search; set to "live" to enable real-time search
model_catalog_json	Path of the model catalog created in the previous step, declaring each model's context window and image input support
base_url	Kimi Code API address, always https://api.kimi.com/coding/v1
env_key	The name of the environment variable holding the API Key (KIMI_API_KEY here — the Key itself goes elsewhere). Codex reads the secret from this variable at startup; you set its value in the next step
wire_api	Wire protocol, must be "responses" to use the Responses API
enabled-reasoning-efforts	Reasoning levels shown in the desktop model picker; desktop only — the CLI does not need this

Step 3: Set the API Key

The recommended approach is an environment variable (the env_key above): the config file contains no plaintext secret, so it can be shared and backed up safely. This is also the officially recommended approach by Codex.

Pick the command for your operating system:

macOS

echo 'export KIMI_API_KEY="sk-kimi-your-key"' >> ~/.zshrc
source ~/.zshrc

Linux

echo 'export KIMI_API_KEY="sk-kimi-your-key"' >> ~/.bashrc
source ~/.bashrc

Windows

setx KIMI_API_KEY "sk-kimi-your-key"

One more step is required for the Codex desktop app: apps launched from the Dock or Finder do not inherit environment variables from your terminal, so the Key must be injected into the current user session. Run in a terminal:

launchctl setenv KIMI_API_KEY "sk-kimi-your-key"

After running it, fully quit the desktop app (Cmd+Q) and reopen it for the change to take effect. Note: the variable does not survive a reboot — run the command again after restarting. Windows does not need this step: setx writes a system environment variable, and restarting the app is enough.

Alternative: write the Key into the config (experimental_bearer_token)

If environment variables do not take effect (for example, GUI apps cannot read them, or CI environments make injection inconvenient), use experimental_bearer_token to write the Key directly into the provider config, replacing env_key:

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.kimi.com/coding/v1"
wire_api = "responses"
experimental_bearer_token = "sk-kimi-your-key"

Plaintext secret risk

With this approach the Key is stored in plaintext in the config file. Do not commit the file to a version-control repository or share it publicly in dotfiles — weigh the trade-off yourself. Do not configure env_key and experimental_bearer_token at the same time.

Step 4: Launch and verify

Open a new terminal, switch to the project directory, and start Codex:

cd /path/to/your/project
codex

Send a hello message in the session — a normal reply means the configuration works.

Signs of a successful setup:

• The startup banner shows model: k3-256k (or your chosen model) and provider: kimi;
• The Model metadata not found warning no longer appears (models.json is in effect).

Using the Codex desktop app

The desktop app reads the same ~/.codex/models.json and ~/.codex/config.toml as the CLI. Follow the CLI configuration above through Step 3, then:

1. (macOS only) Inject the environment variable: GUI apps cannot read variables set in your terminal, so run the following command first to inject KIMI_API_KEY into the user session. On Windows, setx writes a system environment variable, so this step is not needed.

   launchctl setenv KIMI_API_KEY "sk-kimi-your-key"

2. Restart the desktop app: fully quit (Cmd+Q on macOS) and reopen it for the new configuration to load.

3. Pick a model and start chatting: select a Kimi model from the model picker in a new thread.

TIP

The desktop app automatically appends managed blocks (plugins, MCP servers, etc.) to config.toml. This is expected — your manually added Kimi Code configuration is preserved intact, and these auto-generated blocks should not be deleted.

Switching reasoning effort

K3 supports three effort levels: low / high / max. In a Codex CLI session, type /model to re-select the current model, then choose a level from the Select Reasoning Level menu.

After switching, start a new session to avoid extra cost from stale context caches.

FAQ

Error: Missing environment variable: KIMI_API_KEY

The current process cannot read the environment variable. Make sure it is written to the correct shell config file and open a new terminal; on macOS for the desktop app, use the launchctl method from Step 3. If it still fails, switch to experimental_bearer_token.

codex exec cannot run tool commands

In environments with a restricted user namespace (for example, bwrap reporting ENOSPC), Codex's default sandbox does not work. Add --sandbox danger-full-access to run tool commands: codex exec --sandbox danger-full-access "your task". Note that this disables sandbox isolation — commands run directly in your real environment, so only use it with tasks from trusted sources.

Next steps

• Model configuration — compare model capabilities and see the full effort mapping table
• Membership — check model availability and tier requirements