> ## Documentation Index
> Fetch the complete documentation index at: https://platform.kimi.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Kimi API in Codex

This guide explains how to connect the Kimi K2.7 Code model to OpenAI Codex. Codex remains responsible for local code understanding, command execution, and file editing, while Kimi K2.7 Code provides the model inference capability.

> [Codex](https://openai.com/codex/) is a programming agent product from OpenAI. Its interface, configuration options, and supported capabilities may change across Codex versions. This guide is based on the official Kimi API calling method and describes a general integration approach: forwarding Codex model requests to the Kimi API through a compatibility layer.

## When To Use This

If you want to use Kimi's code models inside Codex, follow this guide to complete the setup.

After integration, you still describe requirements, make code changes, run tests, and perform reviews inside Codex. Model requests are forwarded to the Kimi API through a local compatibility layer.

## Recommended Models

| Scenario                                                  | Recommended model          |
| --------------------------------------------------------- | -------------------------- |
| Complex coding, long-context work, multi-step agent tasks | `kimi-k2.7-code`           |
| General coding tasks where output speed matters more      | `kimi-k2.7-code-highspeed` |

`kimi-k2.7-code` and `kimi-k2.7-code-highspeed` belong to the same model family. Both support a 256K context window. The high-speed version is suitable for development scenarios that are more sensitive to response latency.

## How The Integration Works

The Kimi API provides an OpenAI SDK-compatible Chat Completions API at:

```text theme={null}
https://api.moonshot.ai/v1/chat/completions
```

Codex supports custom model providers. According to Codex documentation, Codex can point to model services that support either the Chat Completions API or the Responses API. However, Chat Completions support has been marked as deprecated and may be removed in the future.

For that reason, we recommend using a local compatibility layer that supports Responses API forwarding:

```text theme={null}
Codex -> local compatibility layer/router -> Kimi API
```

The local compatibility layer handles protocol conversion, authentication forwarding, and streaming response adaptation. You can use any compatibility-layer tool approved by your organization. The examples below use a local routing tool such as CC Switch for illustration.

## Prerequisites

Before you begin, make sure you have:

* Installed Codex and confirmed that it works normally.
* Created an API key in Kimi Open Platform or Kimi Code.
* Prepared a local compatibility-layer tool that can forward Codex requests to an OpenAI Chat Completions-compatible backend.
* Confirmed that there are no high-risk automated tasks currently running in the project. Programming agents may call models and tools across multiple rounds, so set a budget first and keep monitoring the session.

Create a Kimi Open Platform API key here:

```text theme={null}
https://platform.kimi.ai/console/api-keys
```

Create a Kimi Code API key here:

```text theme={null}
https://www.kimi.ai/code/console
```

We also recommend configuring a daily project spending budget in the Kimi Open Platform project settings to avoid unexpected costs caused by agent loops.

## Step 1: Verify That The Kimi API Works

Before connecting Codex, first confirm that your API key and model can be called successfully.

```bash theme={null}
curl https://api.moonshot.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -d '{
    "model": "kimi-k2.7-code",
    "messages": [
      { "role": "user", "content": "Please confirm in one sentence that the Kimi API is connected successfully." }
    ]
  }'
```

If the request succeeds, your API key, account balance, and model access permissions are working.

## Step 2: Configure A Local Compatibility Layer With CC Switch

CC Switch is a graphical local model-routing tool. It can provide protocol compatibility and request forwarding between Codex and the Kimi API. If you want a quick setup path, tools like this can be a convenient first choice.

CC Switch is a third-party tool and is not part of the Kimi API. Its installer, UI labels, ports, and routing capabilities may change by version. Use the actual version you installed as the source of truth. On the Kimi side, make sure the API key, model name, and Kimi API address are configured correctly.

### 2.1 Download And Install

Go to the CC Switch release page and choose the installer for your operating system. It usually provides builds for Windows, macOS, Linux, and other platforms.

After installation, start CC Switch and confirm that the application opens normally.

### 2.2 Automatically Configure The Kimi Provider

The automatic configuration feature in CC Switch modifies your existing Codex configuration file. Back up the user-level Codex configuration file before continuing:

```text theme={null}
~/.codex/config.toml
```

In CC Switch, add or select a provider related to Kimi or Kimi For Coding.

If the tool includes a built-in Kimi preset, use that preset first. If you need to enter the values manually, use the following parameters:

| Setting      | Kimi                                             | Kimi For Coding                         |
| ------------ | ------------------------------------------------ | --------------------------------------- |
| API Base URL | `https://api.moonshot.ai/v1`                     | `https://api.kimi.ai/coding/v1`         |
| API Key      | `MOONSHOT_API_KEY` created in Kimi Open Platform | `MOONSHOT_API_KEY` created in Kimi Code |
| Model        | `kimi-k2.7-code` or `kimi-k2.7-code-highspeed`   | `kimi-for-coding`                       |
| Upstream API | OpenAI-compatible Chat Completions               | OpenAI-compatible Chat Completions      |

After you click add, CC Switch automatically modifies the Codex configuration file to add the provider.

### 2.3 Enable Codex Routing

In CC Switch, enable the route or Responses API compatibility mode for Codex. After it is enabled, CC Switch starts a local service address such as:

```text theme={null}
http://127.0.0.1:PORT/v1
```

Record the actual port. If you configure Codex manually, you need to write this address into the Codex configuration yourself.

After setup, check the CC Switch logs to confirm that the service has started and that the currently selected provider is Kimi or Kimi For Coding.

### 2.4 Confirm The Configuration In Codex

After completing the Codex configuration and restarting Codex, check the Codex settings page to confirm that the current provider or model configuration has taken effect.

## Optional: Manually Configure The Codex Provider

Open the user-level Codex configuration file:

```text theme={null}
~/.codex/config.toml
```

Add a custom provider. Replace `PORT` with the actual port of your local compatibility layer.

```toml theme={null}
model = "kimi-k2.7-code"
model_provider = "kimi_via_router"

[model_providers.kimi_via_router]
name = "Kimi K2.7 Code via local router"
base_url = "http://127.0.0.1:PORT/v1"
wire_api = "responses"
```

For Kimi For Coding:

```toml theme={null}
model = "kimi-for-coding"
model_provider = "kimi_code_via_router"

[model_providers.kimi_code_via_router]
name = "Kimi Code via local router"
base_url = "http://127.0.0.1:PORT/v1"
wire_api = "responses"
```

If your local compatibility layer requires Codex to pass through the API key, use an environment variable:

```toml theme={null}
model = "kimi-k2.7-code"
model_provider = "kimi_via_router"

[model_providers.kimi_via_router]
name = "Kimi K2.7 Code via local router"
base_url = "http://127.0.0.1:PORT/v1"
wire_api = "responses"
env_key = "MOONSHOT_API_KEY"
```

For Kimi For Coding:

```toml theme={null}
model = "kimi-for-coding"
model_provider = "kimi_code_via_router"

[model_providers.kimi_code_via_router]
name = "Kimi Code via local router"
base_url = "http://127.0.0.1:PORT/v1"
wire_api = "responses"
env_key = "MOONSHOT_API_KEY"
```

If the API key is already stored in the local compatibility layer, you usually do not need to configure `env_key` again in Codex.

After saving the configuration, restart Codex or open a new Codex session so the configuration takes effect.

Note: Codex provider configuration should be written to the user-level `~/.codex/config.toml`. Project-level `.codex/config.toml` is not suitable for local machine settings such as provider authentication and provider selection.

## Optional: Configure Another Local Compatibility Layer

For any local compatibility layer that supports model routing, complete the following setup:

* Add or select a Moonshot/Kimi provider.
* Set the API Base URL to `https://api.moonshot.ai/v1`.
* Set the API key to the `MOONSHOT_API_KEY` you created in Kimi Open Platform.
* Select `kimi-k2.7-code` or `kimi-k2.7-code-highspeed` as the model.
* Enable a Responses API-compatible route for Codex.
* Record the address exposed to Codex by the local compatibility layer, such as `http://127.0.0.1:PORT/v1`.

Different tools may use different ports and menu names. Follow the UI of the version you installed. We recommend checking the compatibility-layer logs to confirm that requests are being forwarded to the Kimi API.

## Step 3: Verify In Codex

After reopening Codex, use a small task to verify the full request path:

```text theme={null}
Please read the README in the current project and summarize the project's tech stack. Do not modify files.
```

While testing, watch the local compatibility-layer logs and confirm:

* Codex requests the local compatibility-layer address.
* The local compatibility layer forwards requests to `https://api.moonshot.ai/v1/chat/completions` or `https://api.kimi.ai/coding/v1/chat/completions`.
* The requested model is `kimi-k2.7-code`, `kimi-k2.7-code-highspeed`, or `kimi-for-coding`.
* Codex receives streaming output normally and can continue with later steps.

After confirming that the request path is stable, you can ask Codex to perform code changes, run tests, or review code.

## Troubleshooting

| Issue                                             | Possible cause                                                                                              | Fix                                                                                                                      |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Codex still uses the original model after startup | The configuration file did not take effect, or the settings were written to the project-level configuration | Confirm that the configuration is written to `~/.codex/config.toml`, then restart Codex                                  |
| Failed to connect to the local address            | The local compatibility layer is not running, or the port is different                                      | Start the compatibility layer and check the port in `base_url`                                                           |
| 401 or authentication error                       | The API key is missing, expired, or not forwarded correctly                                                 | Reconfigure the API key in the compatibility layer or in the `MOONSHOT_API_KEY` environment variable                     |
| Request format or streaming response error        | Codex and the backend protocol do not match                                                                 | Confirm that the compatibility layer has enabled a Responses API-compatible route                                        |
| Model parameter error                             | Kimi K2.7 Code has fixed requirements for some sampling parameters                                          | Do not force overrides for `temperature`, `top_p`, `n`, penalty parameters, or similar fields in the compatibility layer |
| Token usage grows quickly                         | The agent is making multi-round calls, retrying, or looping through tools                                   | Set a daily project budget, monitor compatibility-layer logs, and interrupt the current Codex task when needed           |

## Usage Tips

* Prefer `kimi-k2.7-code` for complex code changes, cross-file understanding, and long-context tasks.
* Try `kimi-k2.7-code-highspeed` when faster response speed is more important.
* Do not manually override sampling parameters for Kimi K2.7 Code. Keep the default configuration.
* For large repositories, ask Codex to perform read-only analysis first, then make changes and run tests in stages.
* When running Codex for a long time, keep monitoring logs, budget usage, and terminal behavior.