帮助中心 返回首页
最近更新：2025年11月27日 03:19

Codex CLI 完整配置指南（Mac/Windows）

目录

API Key 获取与保存

  1. 访问 https://www.i-coding.shop/console/token，进入 令牌管理。
  2. 点击 添加令牌。
  3. 在弹窗中配置：名称、可选分组、过期时间（推荐永不过期并结合额度控制）、额度/数量、可用模型。
  4. 提交后系统显示新令牌，请立即复制并保存。关闭弹窗后将无法再次查看完整 Key。
  5. 该令牌即 Codex CLI 所需的 API Key，可在列表页随时删除或重新生成。

建议将 Key 存入密码管理器并在 .gitignore 中忽略任何包含 Key 的文件。

环境变量与 Base URL

  • Base URL：https://www.i-coding.shop/v1
  • 必填环境变量：
    OPENAI_API_KEY=<你的令牌>
OPENAI_API_BASE=https://www.i-coding.shop/v1
  • 可选：OPENAI_ORG_ID、OPENAI_PROJECT、OPENAI_API_TYPE=openai 等，按项目需求设置。

Codex CLI 支持从环境变量、.env、~/.codex/config.toml 多层读取，优先级依次为：项目配置 > 全局配置 > 环境变量。

如何选择配置方式？
推荐使用 cc-switch 一键写入配置；如果机器无法安装 GUI，可使用环境变量方式；若需要按项目覆盖，再编辑 ~/.codex/config.toml。请 三选一，无需全部执行。

使用 cc-switch 配置

cc-switch（https://github.com/farion1231/cc-switch/releases），顶部 Claude | Codex | MCP，右上角 添加供应商。

  1. 安装：在 Releases 下载最新版 — Windows 选 .msi（或 Portable.zip 免安装）；macOS 选 .zip 或 .tar.gz；Linux 选 .AppImage（或 .deb，需赋权运行）。
  2. 添加 Codex 供应商（新 UI 要点）：
    • 顶部切到 Codex，点 添加供应商。
    • 配置类型：默认 自定义，可选 Codex Official / PackyCode。
    • 供应商名称：必填，自定义即可。
    • 官网地址：可选。
    • API 请求地址：https://www.i-coding.shop/v1。
    • auth.json (JSON)：确认自动生成：
      { "OPENAI_API_KEY": "sk-粘贴你的令牌" }
      令牌来自 https://www.i-coding.shop/console/token。
    • config.toml (TOML)：可留空，或按需填写；可勾选“写入通用配置”。
  3. 启用与管理：点 添加 返回列表，在卡片上“启用/编辑/删除”；切换 Claude/MCP 查看其他类型。

用 cc-switch 写入后，可跳过手工改 .zshrc 或 config.toml。

macOS/Linux 配置流程

Linux 用户与 macOS 步骤完全一致，如使用 bash 仅需替换配置文件。

安装 Codex CLI

方式一：Homebrew（推荐）

brew install --cask codex

方式二：npm 全局安装（需 Node.js 22+）

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

验证安装

codex --version

配置 API Key 与 Base URL

若已通过 cc-switch 写入配置，可跳过本节。

临时设置

export OPENAI_API_KEY="你的令牌"
export OPENAI_API_BASE="https://www.i-coding.shop/v1"
codex

永久设置（根据 shell 二选一）

先运行 echo $SHELL 判断当前 shell：

  • 输出 .../zsh → 编辑 ~/.zshrc
  • 输出 .../bash → 编辑 ~/.bash_profile
  • 其他 shell 请写入对应 rc 文件

zsh

nano ~/.zshrc
export OPENAI_API_KEY="你的令牌"
export OPENAI_API_BASE="https://www.i-coding.shop/v1"
source ~/.zshrc

bash

echo "export OPENAI_API_KEY='你的令牌'" >> ~/.bash_profile
echo "export OPENAI_API_BASE='https://www.i-coding.shop/v1'" >> ~/.bash_profile
source ~/.bash_profile

验证

echo $OPENAI_API_KEY
codex --version
codex "self test"

若命令返回模型输出，说明认证成功。

Windows 配置流程

安装 Codex CLI

方案一：WSL2 + Linux 安装（最稳定）

wsl --install -d Ubuntu  # 管理员权限

进入 WSL Ubuntu 后按照 macOS/Linux 步骤执行（Homebrew/ npm）。

方案二：官方可执行文件

  1. 访问 https://github.com/openai/codex/releases
  2. 下载 codex-v0.57.0-windows-x86_64.zip
  3. 解压到 C:\tools\codex
  4. 将该目录加入系统 Path（sysdm.cpl → 环境变量 → Path → 新建）
  5. 打开新 PowerShell 验证：
codex --version

方案三：npm 全局安装（需 Node.js 22+）

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

配置 API Key 与 Base URL

若已通过 cc-switch 写入配置，可跳过本节。PowerShell 与 CMD 任选其一。

临时设置

$env:OPENAI_API_KEY="你的令牌"
$env:OPENAI_API_BASE="https://www.i-coding.shop/v1"
codex
set OPENAI_API_KEY=你的令牌
set OPENAI_API_BASE=https://www.i-coding.shop/v1
codex

永久设置

  1. Win + R → sysdm.cpl → Enter。
  2. “环境变量” → “用户变量” → “新建”。
  3. 新建 OPENAI_API_KEY（填令牌）与 OPENAI_API_BASE（填 https://www.i-coding.shop/v1）。
  4. 重新打开终端后执行：
$env:OPENAI_API_KEY
$env:OPENAI_API_BASE

PowerShell 快速写入

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的令牌", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_BASE", "https://www.i-coding.shop/v1", "User")
$env:OPENAI_API_KEY
$env:OPENAI_API_BASE

可选 .env 配置

在项目根目录创建 .env：

OPENAI_API_KEY=你的令牌
OPENAI_API_BASE=https://www.i-coding.shop/v1
OPENAI_API_TYPE=openai

并确保 .env 已加入 .gitignore，防止泄露。

验证

echo %OPENAI_API_KEY%
codex --version
codex "test"

常用命令

codex --version            # 查看版本
codex --help               # 帮助
codex                      # 启动交互式 TUI
codex "prompt"             # 单次执行
codex exec "prompt"        # 自动执行模式
codex --model gpt-5.1-codex "prompt"
codex --input spec.md      # 从文件读取
codex --output result.txt  # 将输出写入文件
codex config               # 查看配置
codex config reset         # 重置配置

配置文件详解

主配置路径

  • macOS/Linux：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml
  • 项目覆盖：./.codex/config.toml

基础配置示例

model = "gpt-5.1-codex"
model_provider = "openai"
preferred_auth_method = "apikey"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
log_level = "info"
request_timeout = 30
openai_api_base = "https://www.i-coding.shop/v1"

高级配置示例

model = "gpt-5.1-codex"
model_provider = "openai"
temperature = 0.7
max_tokens = 4096

[permissions]
allow_bash = true
allow_read = true
allow_write = true
allow_network = false

[api]
base_url = "https://www.i-coding.shop/v1"
timeout = 30
retries = 3

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

在项目目录放置 .codex/config.toml 可以覆盖全局设置，例如：

model = "gpt-5.1-codex-mini"
sandbox_mode = "read-only"
approval_policy = "always"

其他提供商配置

Codex CLI 支持兼容 OpenAI API 的云厂商，例如 Azure OpenAI。示例：

model = "gpt-4"
model_provider = "azure"

[model_providers.azure]
endpoint = "https://xxx.openai.azure.com/"
api_version = "2024-02-15-preview"
deployment = "gpt-4"
api_key = "<azure-key>"

同理可配置其他兼容服务（如通义千问海外站、火山方舟等），只需替换 base_url 与 api_key。

常见问题

npm 安装后运行报 Node 版本不足？
确认 node --version ≥ 22，必要时使用 nvm 升级。
API Key 设置正确仍提示登录？
依次检查 OPENAI_API_KEY 是否生效、OPENAI_API_BASE 是否为 https://www.i-coding.shop/v1，以及 i-Coding 令牌是否过期或被删除。
丢失令牌怎么办？
前往 i-Coding 控制台 删除旧令牌并重新生成，同时更新所有环境变量与配置文件。
如何同时管理多个服务商？
使用项目级 .codex/config.toml，为不同项目指定各自的 model_provider、base_url 与 API Key。
已经用 cc-switch 配置，还需要再改 .zshrc 或 config.toml 吗？
无需重复操作。cc-switch 会根据勾选自动写入目标文件/环境变量并保留备份，除非希望手工覆盖，否则保持现状即可。