Codex CLI 接入指南：把 OpenAI 终端 Agent 接到 OpenStarry 用国产模型

Codex CLI（github.com/openai/codex）是 OpenAI 在 2025 年发布的终端原生 AI 编程 Agent，定位与 Claude Code 完全对标：读写项目文件、执行 Shell 命令、调用 MCP 工具，支持 /approvals、/diff、/reasoning 等斜杠命令，且深度集成 ChatGPT 账号体系。

虽然 Codex CLI 官方绑定 OpenAI 模型，但通过 ~/.codex/config.toml 一行 base_url 配置即可接入任何 OpenAI 兼容端点。本文实测 OpenStarry 全流程：从安装到用 GLM-5.1 完成一次重构任务。完整官方文档可参考 OpenStarry Docs · Codex 章节。

---

一、为什么要在国内使用 Codex CLI

1.1 Codex CLI 的核心价值

• OpenAI 官方出品：与 Codex Web、IDE 插件、PR Review 共享同一套执行引擎
• Rust 实现，启动毫秒级：比 Node.js 写的 Claude Code 启动快 3-5 倍
• 强大的 TUI：流式渲染 diff、多面板布局、Tool 调用可视化
• 原生的 MCP / Skills 支持：可直接消费公司内部的 MCP Server

1.2 为什么走 OpenStarry

1. 国内直连：Codex CLI 直连 OpenAI 经常超时；通过 OpenStarry 国内节点延迟稳定在 30-80ms
2. 用国产旗舰模型：GLM-5.1 中文编程能力强、DeepSeek V4 Flash 极速、Claude Sonnet 4.6 英文推理稳定
3. 统一账期：Codex CLI 同时用 GPT-4o、GLM-5.1、DeepSeek V4 Pro 不再需要 3 个 API Key
4. 企业友好：OpenStarry 支持对公转账 + 增值税专票，Codex CLI 走 ChatGPT 订阅在国内无法报销

推荐套餐：每日深度使用推荐 星途版 ¥99/月 · 20000 次/月；轻度使用选 星序版 ¥9.9/周 · 1000 次/周。计费规则见 计费说明。

---

二、环境准备

2.1 安装 Node.js 22+（Codex CLI 的运行时）

Codex CLI 官方要求 Node.js 22 或更新版本（早期 18 也能跑，但部分 MCP / Skills 需要 22+）。

# macOS（推荐 nvm 装多版本）
brew install nvm
nvm install 22
nvm use 22

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 验证
node -v   # 期望 v22.x.x
npm -v    # 期望 10.x.x

2.2 安装 Codex CLI

# 全局安装
npm install -g @openai/codex

# 国内加速
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

# 验证
codex --version
# 期望：codex-cli 0.x.x

2.3 获取 OpenStarry API Key

1. 访问 openstarry.com 注册账号
2. 进入 Dashboard → API Keys → 创建新 Key
3. 复制（格式 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx）
4. 首次注册会赠送 星痕版 200 次免费调用

---

三、配置 OpenStarry 接入（3 步）

Step 1：创建配置目录

mkdir -p ~/.codex
touch ~/.codex/config.toml

Step 2：写入 config.toml

# ~/.codex/config.toml
# 默认模型（Codex 启动时自动加载）
model = "openstarry/glm-5.1"
model_reasoning_effort = "medium"

# OpenStarry 接入
[model_providers.openstarry]
name = "OpenStarry"
base_url = "https://api.openstarry.com/v1"
env_key = "OPENSTARRY_API_KEY"
wire_api = "chat"
requires_openai_auth = false

# （可选）请求超时
request_timeout = 60

关键字段说明：

• model：使用 provider/model 格式切换，openstarry/ 前缀对应 [model_providers.openstarry] 块
• base_url：填到 v1 路径（与 /v1/chat/completions 兼容）
• env_key：告诉 Codex 从环境变量读 Key，避免配置文件泄露
• wire_api = "chat"：使用 OpenAI Chat Completions 协议（不是 Responses）

Step 3：设置环境变量

# 写入 ~/.zshrc 或 ~/.bashrc
export OPENSTARRY_API_KEY="sk-your-key-here"

# 立即生效
source ~/.zshrc   # 或 source ~/.bashrc

# 验证
echo $OPENSTARRY_API_KEY
# 期望：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

四、第一次启动 & 验证

4.1 启动 Codex

# 进入你的项目目录
cd ~/projects/my-app

# 启动 Codex CLI
codex

# 或一次性命令（不进入 TUI）
codex "解释一下 src/ 目录的结构"

4.2 切模型（最常用）

在 TUI 中按 /model，或直接用 --model 参数：

# 用 GLM-5.1（中文编程首选）
codex --model openstarry/glm-5.1 "把 utils.js 里的 fetch 包装一层超时"

# 用 DeepSeek V4 Pro（复杂推理）
codex --model openstarry/deepseek-v4-pro "重构这个模块，拆分出 Repository 层"

# 用 Claude Sonnet 4.6（英文文档 / 注释）
codex --model openstarry/claude-sonnet-4-6 "为这个函数补全 JSDoc"

# 用 Kimi K2.6（长上下文）
codex --model openstarry/kimi-k2.6 "总结 docs/requirements.md 并列出待办"

4.3 进阶：项目级配置覆盖

如果只想在某个项目内用 Codex 而不影响全局配置，把 config.toml 放到项目根目录下的 .codex/config.toml：

mkdir -p .codex
cat > .codex/config.toml <<'EOF'
model = "openstarry/deepseek-v4-flash"

[model_providers.openstarry]
name = "OpenStarry"
base_url = "https://api.openstarry.com/v1"
env_key = "OPENSTARRY_API_KEY"
wire_api = "chat"
EOF

# 团队共享时，把 .codex/ 加入 git，sk- 仍然从环境变量读

---

五、推荐的模型组合

完整模型 ID 与实时价格见 OpenStarry Docs · 模型列表。

---

六、常见问题

Q1：报错 OPENSTARRY_API_KEY is not set

说明环境变量没生效。终端执行 echo $OPENSTARRY_API_KEY 验证：

• 无输出 → 检查 ~/.zshrc 是否漏写 export，或没 source
• 有输出但 Codex 仍报错 → 用 env | grep OPENSTARRY 确认变量名拼写完全一致

Q2：报错 401 invalid api key

检查 Key 格式：必须以 sk- 开头，长度 ≥ 30。如果用 osr- 开头的老 Key，请到 Dashboard 重新创建。

Q3：报错 404 model not found

模型 ID 区分大小写，openstarry/glm-5.1（小写）才是正确的。如果写成 openstarry/GLM-5.1 会失败。完整列表：OpenStarry Docs · 模型列表。

Q4：流式输出断断续续？

这是 Codex 默认开启的渐进式渲染，与 OpenStarry 无关。如需关闭，在配置中加：

[model_providers.openstarry]
stream = true
stream_idle_timeout_ms = 30000

Q5：能否在 codex 命令里临时切换到 OpenAI 官方？

可以。Codex 支持多 provider 切换：

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

[model_providers.openstarry]
name = "OpenStarry"
base_url = "https://api.openstarry.com/v1"
env_key = "OPENSTARRY_API_KEY"
wire_api = "chat"

运行时用 --model 即可选择 provider：

codex --model openai/gpt-4o    "用官方 GPT-4o 处理"
codex --model openstarry/glm-5.1 "用 GLM-5.1 处理"

---

总结

Codex CLI 是 OpenAI 官方对标 Claude Code 的终端 Agent，Rust 编写、毫秒启动、深度 MCP 集成。通过 OpenStarry 一个 sk- 开头 API Key + 一行 base_url，就能用上 GLM-5.1、DeepSeek V4、Claude Sonnet 4.6 等 40+ 国产 + 国际旗舰模型，按 星途版 ¥99/月 · 20000 次/月 的 Coding Plan 套餐计费，成本可控。

回看 3 步核心流程：npm i -g @openai/codex → 创建 ~/.codex/config.toml → export OPENSTARRY_API_KEY=sk-... → codex --model openstarry/glm-5.1 "你的需求"。整个过程不超过 5 分钟。