词元 API 文档

Appearance

Codex CLI ​

Codex CLI 是 OpenAI 的代理式编程工具，可以在终端中阅读代码、修改文件、运行命令、审查 diff，并协助完成调试、测试、重构和文档维护。

本文说明如何将 Codex CLI 接入词元 API。

准备工作 ​

使用前请先确认：

  • 已安装 Node.js 与 npm。
  • 已安装 Git。
  • Windows 用户推荐使用 WSL2；如果直接使用 PowerShell，遇到脚本策略问题时可改用 codex.cmd。
  • 已在词元 API 控制台创建可用 API Key。
  • API Key 所在分组包含 Codex CLI 要使用的模型。

控制台入口：

text
https://code.ciyuanapi.xyz

令牌管理：

text
https://code.ciyuanapi.xyz/token

OpenAI 兼容 Base URL：

text
https://code.ciyuanapi.xyz/v1

检查环境：

bash
node -v
npm -v
git --version

安装 Codex CLI ​

使用 npm 安装：

bash
npm install -g @openai/codex

macOS 也可以使用 Homebrew：

bash
brew install codex

验证安装：

bash
codex --help
codex --version

Windows PowerShell 如果提示禁止运行脚本，可以使用：

powershell
codex.cmd

Windows 如果安装或运行时报权限错误，请用管理员身份打开 PowerShell 或 CMD 后重试。

配置词元 API ​

Codex CLI 的配置文件常见位置：

text
~/.codex/config.toml
%USERPROFILE%\.codex\config.toml

可以在配置文件中加入词元 API provider：

toml
model = "gpt-5.4-mini"
model_provider = "ciyuanapi"

[model_providers.ciyuanapi]
name = "ciyuanapi"
base_url = "https://code.ciyuanapi.xyz/v1"
env_key = "OPENAI_API_KEY"

然后在环境变量里设置 API Key。

macOS / Linux / WSL：

bash
export OPENAI_API_KEY="你的词元 API Key"

Windows PowerShell：

powershell
$env:OPENAI_API_KEY="你的词元 API Key"

Windows CMD：

cmd
set OPENAI_API_KEY=你的词元 API Key

如果你的 Codex 版本要求显式指定接口协议，可以在 provider 下补充：

toml
wire_api = "responses"

如果要让 Codex 到词元 API 使用 WebSocket，按当前 Codex 版本支持情况添加：

toml
supports_websockets = true

AGENTS.md ​

建议在项目根目录或 ~/.codex/ 放置 AGENTS.md，写明项目规范、编码要求、测试命令和安全边界。

常见内容包括：

  • 项目目录结构。
  • 代码风格。
  • 测试命令。
  • 不允许修改的目录。
  • 部署或提交注意事项。

启动与常用命令 ​

交互模式：

bash
codex
codex "fix lint errors"

非交互模式：

bash
codex exec "count lines of code in this project"

允许自动修改工作区：

bash
codex exec --full-auto "fix lint errors"

非 Git 目录运行：

bash
codex exec --skip-git-repo-check "describe the files here"

指定模型：

bash
codex -m gpt-5.4-mini

常用 TUI 命令：

命令作用
/model切换模型与推理参数
/plan切换计划模式
/approvals设置批准策略
/permissions配置命令权限
/review代码审查
/diff查看当前差异
/status查看模型、沙盒、token 等状态
/init生成 AGENTS.md
/mcp查看 MCP 工具
/exit 或 /quit退出

权限与沙盒 ​

Codex 的安全边界主要由两类配置决定：

配置说明
approval_policy什么时候需要用户确认
sandbox_mode命令可以访问哪些资源

推荐日常使用：

toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

只读分析：

toml
sandbox_mode = "read-only"
approval_policy = "never"

需要网络访问时，可在 workspace-write 下补充：

toml
[sandbox_workspace_write]
network_access = true

不建议日常使用 danger-full-access 或 --yolo，除非已经在容器或虚拟机中隔离。

常见问题 ​

codex: command not found ​

  • 关闭并重新打开终端。
  • 检查 npm 全局安装路径是否在 PATH 中。
  • Windows PowerShell 可以尝试 codex.cmd。

running scripts is disabled ​

这是 PowerShell 执行策略限制。可以直接使用：

powershell
codex.cmd

codex exec 提示不是 Git 仓库 ​

可以使用：

bash
codex exec --skip-git-repo-check "describe the files here"

一直只读，无法修改文件 ​

在 TUI 中执行 /status 检查沙盒状态。需要写入时可使用：

bash
codex --sandbox workspace-write

或在配置文件中写入：

toml
sandbox_mode = "workspace-write"

Windows 乱码 ​

推荐使用 WSL2。PowerShell 可以尝试切换 UTF-8：

powershell
chcp 65001

并确认文件与终端均使用 UTF-8。