云原生 Codex CLI 快速入门指南

欢迎使用云原生 Codex CLI！这是基于官方 Codex 配置 GPTMeta API 中转进行使用的一个强大AI编程助手项目。

系统要求

要求	细节
操作系统	macOS 12+、Ubuntu 20.04+/Debian 10+ 或通过 WSL2 的Windows 11
Git（可选，推荐）	2.23+ 内置 PR 助手
内存	最低 4 GB（建议 8 GB）

1. 安装 Codex CLI

任选一种方式：

npm（通用）

npm i -g @openai/codex
# 或在有时需要的原生包名：
# npm i -g @openai/codex@native
codex --version

Homebrew（macOS）

brew update
brew install codex
codex --version

如遇 codex 无法执行或 Node 版本过旧，请升级 Node（常见需要 Node 22+），或改用 Homebrew 安装。

---

2. 准备 GPTMeta Pro API Key 并配置 Codex

注册 GPTMeta Pro API 账户

步骤1：访问注册页面

1. 访问 https://coultra.blueshirtmap.com
2. 点击注册按钮创建新账户
3. 填写必要的注册信息

步骤2：创建API密钥

1. 登录成功后，进入API密钥管理页面
2. 创建一个新的API密钥分组

3. 选择"高速稳定渠道"作为分组名称
4. 生成并复制您的API密钥

配置 Codex

Codex 启动时会在 ~/.codex/ 读取 config.toml。若不存在就新建：

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

在 config.toml 中加入（按需修改）：

# 顶层默认
model = "gpt-4o"            # 按 GPTMeta Pro API 实际可用模型填写
model_provider = "coultra"  # 设置默认 provider

[model_providers.coultra]
name = "GPTMeta Pro API (OpenAI-compatible)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "你的GPTMeta_Pro_API密钥"    # 直接填写您的API密钥
wire_api = "chat"           # 走 OpenAI Chat Completions 协议

# 可选：定义一个 profile，便于命令行快速切换
[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"      # 需要时再询问是否执行
sandbox_mode = "workspace-write"    # 允许在当前工程写文件，依旧禁网

关键字段说明：

• model / model_provider：默认模型与默认提供者。
• [model_providers.<id>].base_url：你的服务 /v1 根；Codex 将以 Chat Completions 线协议交互（通常 POST {base_url}/chat/completions）。
• env_key：直接填写您的 GPTMeta Pro API 密钥。
• wire_api：线协议类型；兼容 Chat Completions 用 "chat"。
• profiles.* 与 --profile：将一组配置打包，运行时快速切换。

---

3. 运行与验证

确保您已完成配置文件设置（见第 2 步），然后：

# 用 profile 运行
codex --profile coultra "用中文解释当前仓库结构"

# 或直接默认运行（已把 provider 设为 coultra）
codex "生成一个 Python 脚本，从 API 拉取数据并保存为 CSV"

运行时，Codex 会在本地沙箱里"看代码、改文件、执行命令"。遇到需要权限时根据 approval_policy 提示确认；workspace-write 允许只在项目目录内写文件，同时仍禁网。

---

4. 沙箱 / 审批策略快速参考

• 审批策略：

  • --ask-for-approval 或配置 approval_policy 控制交互程度。
  • --full-auto 为便捷旗标（较少打扰，仍在沙箱内）。

• 沙箱级别：

  • read-only：只读（不写文件、禁网）
  • workspace-write：可写当前工程目录、禁网
  • danger-full-access：不建议，等同关闭沙箱
  • 命令行可用 --sandbox MODE，配置可 sandbox_mode="MODE"。

需要临时联网？当前版本主打"默认禁网"的安全策略，谨慎使用"危险"模式或后续放网选项。

---

5. 常见问题排查（FAQ）

① 401/403：API Key 无效或余额不足

• 重新在 GPTMeta Pro API 后台生成钥匙；确认配置文件中的 env_key 字段已正确填写您的API密钥。
• 在 CI 中用 Secrets 注入环境变量，避免硬编码。

② 404 / "Resource not found"：base_url 写错

• 多数兼容实现要求 base_url 指向 …/v1；部分平台（如 Azure）路径还需额外片段，路径不全会 404。

③ --profile 没生效或部分键未加载

• 升级到较新版本；旧版本对 profile 的若干键存在已知问题。

④ NPM 安装后 codex 不可用或版本不对

• 升级 Node（建议 22+），或改用 Homebrew 安装；近期版本对 npm 包与行为有调整。

⑤ 本地/第三方 provider 连不上或端口不对

• 确认 base_url 正确；早期版本对 base_url/端口的 bug 可通过升级解决。

---

6. 一份可直接复用的最小可行配置（MVP）

# ~/.codex/config.toml
model = "gpt-4o"
model_provider = "coultra"

[model_providers.coultra]
name = "GPTMeta Pro API (OpenAI-compatible)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "你的GPTMeta_Pro_API密钥"    # 直接填写您的API密钥
wire_api = "chat"

[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

启动命令：

export COULTRA_API_KEY="你的密钥"
codex --profile coultra "给这个仓库添加一个 CLI 子命令"

---

7. 高级使用技巧

CLI 参考

命令	目的	例子
codex	交互式TUI	codex
codex "..."	交互式 TUI 的初始提示	codex "fix lint errors"
codex exec "..."	非交互式"自动化模式"	codex exec "explain utils.ts"

非交互/CI模式

在管道中以无头方式运行 Codex。示例 GitHub Action 步骤：

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

模型上下文协议（MCP）

通过在 ~/.codex/config.toml 中定义一个 mcp_servers 部分，可以将 Codex CLI 配置为使用 MCP 服务器。它旨在反映 Claude 和 Cursor 等工具在其各自的 JSON 配置文件中的 mcpServers 定义方式，尽管 Codex 的格式略有不同，因为它使用的是 TOML 而不是 JSON，例如：

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }