Codex CLI 配置笔记：自定义 Base URL、API Key 和默认模型

在使用 Codex CLI 做本地项目开发时，很多问题并不是“模型会不会写代码”，而是配置没有填对。

常见的配置项主要有三个：

• Base URL
• API Key
• Model

只要这三项对应正确，Codex CLI 就可以在项目目录里读取代码、分析文件、辅助修改和生成说明文档。

这篇文章记录一下 Codex CLI 的基本使用方式，以及如何配置自定义模型入口。

1. Codex CLI 适合什么场景

Codex CLI 更适合放在真实项目目录里使用，而不是只用来生成一段孤立代码。

比较常见的场景有：

• 分析项目目录结构
• 解释某个模块的实现逻辑
• 根据需求修改已有代码
• 根据报错定位问题
• 生成 README 或接口说明
• 给现有代码补测试
• 检查当前 Git diff
• 做代码 Review

例如可以这样使用：

帮我分析一下这个项目的目录结构，并说明主要模块的作用。

或者：

帮我检查当前 Git diff，重点看是否有明显 Bug。

2. 配置时需要关注的三项

无论使用哪种兼容模型服务，配置思路基本都类似：

Base URL: 模型服务接口地址
API Key: 访问密钥
Model: 默认模型名称

可以先把这几项整理成环境变量：

AI_API_BASE_URL=https://your-api.example/v1
AI_API_KEY=sk-xxxxxx
AI_MODEL=gpt-5.5

这里的 gpt-5.5 是默认模型示例。实际使用时，以自己的服务后台可用模型为准。

3. macOS / Linux 配置方式

先创建 Codex 配置目录：

mkdir -p ~/.codex

然后编辑配置文件：

nano ~/.codex/config.toml

示例配置：

model = "gpt-5.5"

[model_providers.custom]
name = "custom"
base_url = "https://your-api.example/v1"
wire_api = "responses"

[profiles.custom]
model_provider = "custom"
model = "gpt-5.5"

再设置 API Key：

export OPENAI_API_KEY="sk-xxxxxx"

修改完成后，建议重新打开终端，再进入项目目录测试。

4. Windows 配置方式

Windows 的配置目录一般在：

%USERPROFILE%\.codex

可以在 PowerShell 中创建目录：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"

然后创建或编辑：

%USERPROFILE%\.codex\config.toml

写入示例：

model = "gpt-5.5"

[model_providers.custom]
name = "custom"
base_url = "https://your-api.example/v1"
wire_api = "responses"

[profiles.custom]
model_provider = "custom"
model = "gpt-5.5"

PowerShell 临时设置密钥：

$env:OPENAI_API_KEY="sk-xxxxxx"

如果希望长期生效，可以根据自己的系统习惯写入用户环境变量。

5. 进入项目目录测试

配置完成后，进入任意项目目录：

cd your-project

然后启动 Codex CLI，先问一个简单问题：

请介绍一下这个项目的目录结构。

如果能正常返回，说明基础配置已经可用。

接下来可以尝试更具体的任务：

帮我分析登录接口的实现逻辑，先不要修改代码。

或者：

帮我给 README 补充启动方式和环境变量说明。

6. 建议添加 AGENTS.md

如果项目经常使用 Codex，可以在项目根目录放一个 AGENTS.md。

这个文件可以写项目约定，例如：

# AGENTS.md

## 项目说明

这是一个 Web 项目。

## 常用命令

- 构建：npm run build
- 测试：npm test

## 修改要求

- 不要提交密钥
- 不要随意修改接口返回结构
- 修改后先查看 Git diff

这样 Codex 在处理任务时，更容易按项目规则执行。

7. 常见问题

7.1 返回 401 或 403

优先检查：

1. API Key 是否复制完整
2. Key 前后是否多了空格
3. Base URL 是否填写正确
4. 当前 Key 是否有模型权限
5. 模型名称是否存在

7.2 模型不可用

检查 config.toml 里的模型名称：

model = "gpt-5.5"

如果服务端没有这个模型，就需要换成实际可用的模型名。

7.3 配置没有生效

检查配置文件路径：

macOS / Linux：

~/.codex/config.toml

Windows：

%USERPROFILE%\.codex\config.toml

修改后建议重新打开终端。

8. 用脚本做一次连通性测试

如果不确定配置是否正常，可以先用 Node.js 测试接口。

const baseURL = process.env.AI_API_BASE_URL;
const apiKey = process.env.AI_API_KEY;
const model = process.env.AI_MODEL || "gpt-5.5";

async function main() {
  const response = await fetch(`${baseURL}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      model,
      messages: [
        {
          role: "user",
          content: "请用三句话介绍 Codex CLI 适合做什么。",
        },
      ],
    }),
  });

  if (!response.ok) {
    const text = await response.text();
    throw new Error(`Request failed: ${response.status} ${text}`);
  }

  const data = await response.json();
  console.log(data.choices?.[0]?.message?.content);
}

main().catch(console.error);

运行前设置环境变量：

export AI_API_BASE_URL="https://your-api.example/v1"
export AI_API_KEY="sk-xxxxxx"
export AI_MODEL="gpt-5.5"

Windows PowerShell：

$env:AI_API_BASE_URL="https://your-api.example/v1"
$env:AI_API_KEY="sk-xxxxxx"
$env:AI_MODEL="gpt-5.5"

9. 示例：替换成自己的接口地址

上面的 https://your-api.example/v1 只是占位地址。实际使用时，把它替换成自己的 OpenAI 兼容接口地址即可。

例如：

AI_API_BASE_URL=https://kkflow.org/v1
AI_API_KEY=sk-xxxxxx
AI_MODEL=gpt-5.5

对应的 config.toml：

model = "gpt-5.5"

[model_providers.custom]
name = "custom"
base_url = "https://kkflow.org/v1"
wire_api = "responses"

[profiles.custom]
model_provider = "custom"
model = "gpt-5.5"

10. 总结

Codex CLI 的配置重点并不多，主要就是：

1. 确认 Base URL
2. 配置 API Key
3. 填写默认模型
4. 在项目目录里测试
5. 根据需要补充 AGENTS.md

配置完成后，Codex CLI 就可以围绕项目代码做分析、修改、文档生成和代码检查。

11. 参考配置

我自己测试时使用的是 kkflow.org，主要是把它作为 OpenAI 兼容接口地址接入 Codex CLI。

配置时可以参考：

官网地址：https://kkflow.org
Base URL：https://kkflow.org/v1
默认模型：gpt-5.5

如果你的 Codex CLI 支持自定义 Base URL，可以把 https://kkflow.org/v1 填进去，再配合自己的 API Key 使用。这样就可以在 Codex 里调用对应模型，适合做项目分析、代码修改、README 生成和日常开发辅助。