Codex CLI 使用教程

Codex CLI 在终端中运行，适合让 AI 阅读项目、修改代码和执行命令。Codex CLI、桌面端和 IDE 插件共用用户目录中的 .codex 配置。

1. 准备信息

先在 DuckMans 后台创建一个专用 Key，参见创建 API Key。你需要：

配置项	内容
Base URL	https://duckmans.com/v1
API Key	YOUR_API_KEY
模型	后台当前可用模型 ID
API 协议	Responses

2. 安装 Codex CLI

已经安装 Node.js 的用户可以执行：

npm install -g @openai/codex
codex --version

也可以按 Codex CLI 官方文档 选择当前系统支持的安装方式。Windows 如果提示 PowerShell 禁止执行脚本，可在确认命令来源后为当前用户调整执行策略：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

3. 创建 .codex 目录

系统	配置目录
macOS / Linux / WSL	~/.codex
Windows	%USERPROFILE%\.codex

macOS、Linux 或 WSL：

mkdir -p ~/.codex

Windows PowerShell：

New-Item -ItemType Directory -Force $HOME\.codex

4. 登录共享认证存储

不要手动创建或修改 auth.json。使用 Codex 自带的登录命令，Codex 会生成完整的共享认证文件。

macOS、Linux 或 WSL 可先把 Key 安全读入当前终端的临时变量，再通过标准输入登录：

old_stty=$(stty -g)
trap 'stty "$old_stty"' EXIT INT TERM
stty -echo
printf 'DuckMans API Key: ' >&2
IFS= read -r OPENAI_API_KEY
stty "$old_stty"
trap - EXIT INT TERM
printf '\n' >&2
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY old_stty

Windows PowerShell：

$secureKey = Read-Host "DuckMans API Key" -AsSecureString
$keyPtr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
try {
  $OPENAI_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($keyPtr)
  $OPENAI_API_KEY | codex login --with-api-key
} finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($keyPtr)
  Remove-Variable OPENAI_API_KEY, secureKey -ErrorAction SilentlyContinue
}

这两种写法都不会把真实 Key 直接放进命令行历史。登录成功后，Codex 会在 .codex 目录中保存共享认证状态。Codex CLI 0.144.4 的 codex doctor --json 将 API Key 模式报告为 stored auth mode=api_key。Codex CLI、独立 Codex Desktop App 和 IDE 插件会读取同一用户级配置与认证缓存。

5. 写入公共配置

创建 ~/.codex/config.toml：

model = "YOUR_MODEL_ID"
model_provider = "duckmans"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.duckmans]
name = "DuckMans"
base_url = "https://duckmans.com/v1"
wire_api = "responses"
requires_openai_auth = true

requires_openai_auth = true 表示 DuckMans Provider 使用前一步由 codex login --with-api-key 创建的共享认证存储。不要再给 Provider 添加 env_key，也不要把真实 Key 写入 config.toml。

把 YOUR_MODEL_ID 替换为 DuckMans 后台当前可用模型 ID，字符和大小写必须完全一致。先使用这份最小配置，确认可用后再按 Codex 配置参考 增加其他选项。

6. 启动和测试

进入一个测试项目：

cd 你的项目目录
codex

发送只读任务：

请先只读取当前目录，列出主要文件，不要修改任何内容。

确认能返回目录信息后，再逐步授权修改。新手不要使用跳过审批或沙箱的启动参数。

常见问题

• 401：重新运行 codex login --with-api-key，通过标准输入保存完整 API Key；不要手动修补认证文件。
• 403：检查当前 Key 的分组是否允许调用所选模型和协议。
• 404：确认 base_url 恰好是 https://duckmans.com/v1，没有漏写或重复 /v1。
• 模型不存在：把 model 改为后台当前可用模型 ID。
• 修改不生效：完全退出 Codex 后重开；桌面端和 IDE 插件也会读取同一份配置。

配置检查与回滚

保存后可先运行：

codex doctor --json
codex login status

检查 config.load、config.toml 解析、model provider 与认证模式，不要把包含环境路径或认证信息的完整诊断输出公开。修改前备份 ~/.codex/config.toml；失败时恢复备份并完全重启 CLI、App 与 IDE。

确认 `config.load`、`config.toml parse` 和 `auth.credentials` 均为 `ok`，`model provider` 为 `duckmans`。