# Codex 教程

Codex 接入教程，说明如何配置 KaiyunCode API Key、Base URL、模型选择和常见问题，帮助开发者快速使用 AI 编程助手。

Canonical: https://kaiyuncode.com/tutorials/codex
Markdown: https://kaiyuncode.com/tutorials/codex.md

## 接入要点

Codex CLI 使用 OpenAI 兼容鉴权，但本教程推荐把 wire_api 设置为 responses，并把 base_url 指向 https://kaiyuncode.com/v1。

把示例中的“在这里替换成你的_API_KEY”替换成 KaiyunCode 后台创建的 API Key；model 改成你账号已开通的 GPT 模型名称。

- 配置目录：Windows 为 %USERPROFILE%\.codex，macOS/Linux 为 ~/.codex。
- auth.json 保存 OPENAI_API_KEY。
- config.toml 保存模型、provider、wire_api 和 base_url。
- 验证方式：运行 codex，发送“您好！”或让它解析当前项目。

## 安装 Codex CLI

Codex CLI 需要 Node.js 18+。安装完成后重新打开终端，避免旧 PATH 缓存影响命令识别。

### Windows PowerShell

```powershell
node --version
npm install -g @openai/codex
```

### macOS / Linux

```bash
node --version
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
```

## 写入 Windows 配置

在 PowerShell 中执行下面脚本。它会创建 .codex 目录，并用 UTF-8 无 BOM 覆盖写入 auth.json 与 config.toml。

### PowerShell

```powershell
# 目标目录
$dir = Join-Path $env:USERPROFILE ".codex"

# 创建目录（存在不报错）
New-Item -ItemType Directory -Path $dir -Force | Out-Null

# 写 auth.json（UTF-8 无 BOM，覆盖）
$auth = @'
{
  "OPENAI_API_KEY": "在这里替换成你的_API_KEY"
}
'@
[System.IO.File]::WriteAllText(
  (Join-Path $dir "auth.json"),
  $auth,
  (New-Object System.Text.UTF8Encoding($false))
)

# 写 config.toml（UTF-8 无 BOM，覆盖）
$config = @'
model_provider = "custom"
model = "gpt-5.4-mini-plus" #替换成你想用的GPT模型
disable_response_storage = true
network_access = "enabled"

[model_providers]
[model_providers.custom]
name = "kaiyuncode"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://kaiyuncode.com/v1"
'@
[System.IO.File]::WriteAllText(
  (Join-Path $dir "config.toml"),
  $config,
  (New-Object System.Text.UTF8Encoding($false))
)
```

## 写入 macOS / Linux 配置

在终端中执行下面脚本。OPENAI_API_KEY 只替换引号里的示例文字，其余字段可直接保留。

### Shell

```bash
# 目标目录
dir="$HOME/.codex"
mkdir -p "$dir"

# 写 auth.json（覆盖）
cat > "$dir/auth.json" << 'EOF'
{
  "OPENAI_API_KEY": "在这里替换成你的_API_KEY"
}
EOF

# 写 config.toml（覆盖）
cat > "$dir/config.toml" << 'EOF'
model_provider = "custom"
model = "gpt-5.4-mini-plus" #替换成你想用的GPT模型
disable_response_storage = true
network_access = "enabled"

[model_providers]
[model_providers.custom]
name = "kaiyuncode"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://kaiyuncode.com/v1"
EOF
```

## 验证 Codex 接入

确认文件已写入，再启动 codex 输入“您好！”测试调用链路。能正常回复且 KaiyunCode 后台出现调用记录，就说明接入成功。

### Windows PowerShell

```powershell
Get-Content "$env:USERPROFILE\.codex\auth.json"
Get-Content "$env:USERPROFILE\.codex\config.toml"
codex
```

### macOS / Linux

```bash
cat "$HOME/.codex/auth.json"
cat "$HOME/.codex/config.toml"
codex
```

## Codex 常见问题

- 如果 Codex 提示模型不可用，先换成 KaiyunCode 已开通的 GPT 模型名称。
- 如果提示未登录或鉴权失败，检查 auth.json 的 OPENAI_API_KEY 是否只替换了示例文字，没有删除 JSON 引号。
- 如果请求走错官方 OpenAI 地址，检查 config.toml 是否存在 base_url = "https://kaiyuncode.com/v1"，以及 model_provider 是否为 custom。
- 如果 npm 安装较慢，macOS/Linux 示例已使用 npmmirror 镜像源。