Kimi Code 文档

Appearance

在 Codex 中使用 ​

Codex 是 OpenAI 提供的编程 Agent。Kimi Code 服务端原生支持 OpenAI Responses API（流式/非流式、reasoning、function calling 均可用），Codex CLI、桌面端可以通过自定义 model provider 直连，无需任何本地路由或协议转换工具——本文介绍具体配置方法。

OpenAI Responses API 支持文本和图片输入，暂不支持视频输入。如需分析视频，可先用 ffmpeg 提取关键帧后交给模型。

会员权限 ​

配置前先了解自己的会员档位，再根据下表选择合适的模型：

会员档位可用模型上下文窗口
Andantekimi-for-coding256K
Moderatok3
k3-256k
kimi-for-coding		均为 256K
Allegretto 及以上k3
k3-256k
kimi-for-coding
kimi-for-coding-highspeed		k3：最高 1M
k3-256k：256K
kimi-for-coding：256K
kimi-for-coding-highspeed：256K

模型上新推荐

k3-256k 全新上线，256K 上下文内效果与 k3 相同，但 k3（1M）消耗约为 k3-256k 两倍。k3-256k 适合日常问答、代码补全、常规功能开发、单文件或少量文件修改场景。如从 k3（1M 版本）切换至 k3-256k，建议先压缩上下文再切换。

准备工作 ​

  1. 在 Kimi Code 控制台 创建并保存 API Key。
  2. 安装 Codex CLI：
bash
npm install -g @openai/codex

第一步：创建模型目录 models.json ​

在 Codex 配置目录下创建 models.json：

text
~/.codex/models.json
text
C:\Users\<用户名>\.codex\models.json

写入以下内容（此处以 K3 系列模型为例）：

json
{
  "models": [
    {
      "slug": "k3",
      "display_name": "Kimi K3",
      "description": "Kimi K3，1M 上下文",
      "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 上下文",
      "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"]
    }
  ]
}

第二步：编写 config.toml ​

Codex CLI 的配置文件路径：

text
~/.codex/config.toml
text
C:\Users\<用户名>\.codex\config.toml

写入以下内容（文件不存在则新建）：

toml
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"]

各字段含义：

配置项说明
model默认使用的模型。推荐 k3-256k（更省配额），有 1M 上下文需求时用 k3
model_provider默认使用的 provider，对应下方 [model_providers.kimi] 的表名
web_search联网搜索开关。Kimi Code 端点已支持联网搜索，设为 "live" 启用实时搜索
model_catalog_json上一步创建的模型目录文件路径，声明模型的上下文窗口与图片输入能力
base_urlKimi Code 的 API 地址，固定为 https://api.kimi.com/coding/v1
env_key存放 API Key 的环境变量名称（这里填 KIMI_API_KEY，不是填 Key 本身）。Codex 启动时从同名环境变量读取密钥，变量的值在下一步设置
wire_api请求使用的协议，必须填 "responses" 以走 Responses API
enabled-reasoning-efforts桌面端模型选择器中显示的思考档位，仅影响桌面端，CLI 无需此配置

第三步：设置 API Key ​

推荐通过环境变量提供 Key（即上面的 env_key 方式）：配置文件中不含明文密钥，可以安全分享、备份，也是 Codex 官方推荐的方式。

按操作系统选择对应命令：

sh
echo 'export KIMI_API_KEY="sk-kimi-你的key"' >> ~/.zshrc
source ~/.zshrc
sh
echo 'export KIMI_API_KEY="sk-kimi-你的key"' >> ~/.bashrc
source ~/.bashrc
powershell
setx KIMI_API_KEY "sk-kimi-你的key"

使用 Codex 桌面 App 时还需要一步：从 Dock 或访达启动的 App 读不到终端里的环境变量，需要把 Key 注入当前用户会话。在终端执行：

sh
launchctl setenv KIMI_API_KEY "sk-kimi-你的key"

执行后完全退出桌面 App（Cmd+Q）再重新打开，才会生效。注意：该变量在重启电脑后失效，需要重新执行。Windows 没有这一步——setx 写入的是系统环境变量，重启 App 即可。

备选：写入配置文件（experimental_bearer_token） ​

如果遇到环境变量不生效的问题（例如 GUI 应用读不到环境变量、CI 环境不便注入等），可以改用 experimental_bearer_token，把 Key 直接写在 provider 配置里代替 env_key：

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

明文密钥风险

此方式下 Key 以明文存储在配置文件中，请勿将该文件提交到版本仓库或随 dotfiles 公开分享，是否使用请自行权衡。env_key 与 experimental_bearer_token 两种方式不要同时配置。

第四步：启动并验证 ​

新开一个终端，进入需要使用的项目目录，直接启动 Codex：

bash
cd /path/to/your/project
codex

在会话里发一句 hello，能正常返回结果就说明配置已生效。

配置成功的标志：

  • 启动信息中显示 model: k3-256k（或你选用的模型）、provider: kimi；
  • 不再出现 Model metadata not found 警告（models.json 已生效）。

在 Codex 桌面端中使用 ​

桌面端与 CLI 读取同一份 ~/.codex/models.json 和 ~/.codex/config.toml，可按照 CLI 的配置过程完成前三步，随后操作下列步骤：

  1. （仅 macOS）注入环境变量：GUI 应用读不到在终端里配置的变量，先执行下面的命令，把 KIMI_API_KEY 注入用户会话。Windows 的 setx 写入的是系统环境变量，无需这一步。

    sh
    launchctl setenv KIMI_API_KEY "sk-kimi-你的key"

  2. 重启桌面 App：完全退出（macOS 为 Cmd+Q）再重新打开，新的配置才会被加载。

  3. 选择模型开始对话：在模型选择器里选择 Kimi 的模型，打开新线程即可开始使用。

TIP

桌面端运行时会自动向 config.toml 追加插件、MCP 等管理字段，属正常现象；手动添加的 Kimi Code 配置会被完整保留，请勿删除这些自动生成的区块。

切换思考程度（effort） ​

K3 支持 low / high / max 三档思考程度。在 Codex CLI 会话中，输入 /model 重新选中当前模型，然后在 Select Reasoning Level 菜单中选择档位。

切换档位后建议新建会话，避免旧上下文缓存失效带来的额外消耗。

常见问题 ​

报错 Missing environment variable: KIMI_API_KEY ​

当前进程读不到环境变量。确认已写入正确的 shell 配置文件并新开终端；macOS 桌面 App 参考第三步的 launchctl 方法；仍有问题可改用 experimental_bearer_token。

codex exec 无法执行工具命令 ​

在 user namespace 受限的环境（例如 bwrap 报 ENOSPC）下，Codex 的默认沙箱无法工作，codex exec 需要加上 --sandbox danger-full-access 才能执行工具命令，即 codex exec --sandbox danger-full-access "你的任务"。注意该参数会关闭沙箱隔离，命令将直接在你的真实环境中执行，请确认任务来源可信后再使用。

下一步 ​

  • 模型配置 — 查看模型的能力对比和完整 effort 映射表
  • 会员权益 — 确认可用模型与档位要求