Codex 接入教程
分别介绍 Codex UI 客户端和 Codex CLI，并配置 Base URL、API Key、模型接入 JiaPi
先理解两种 Codex
Codex 可以按使用方式分成两类：一种是有图形界面的 UI 客户端，适合 Windows 和 macOS 桌面用户；另一种是命令行 CLI，通常依赖 Node.js/npm，适合终端、WSL、Linux、服务器和自动化场景。
怎么选？
如果你只是 Windows/macOS 桌面使用，先选 UI 客户端；如果你在终端、WSL、Linux 服务器或自动化脚本里使用，选 CLI。
一、准备 JiaPi 参数
UI 客户端和 CLI 都需要同一组 JiaPi 参数。
Base URL
https://ai-api.jiapi.com
API Key
JiaPi 控制台创建的真实密钥。
模型名称
以 JiaPi 当前可用模型为准，本文示例使用 gpt-5.4。
测试项目
准备一个低风险本地项目，用来验证 Codex 是否能读目录。
Base URL 不要写错
只填写 https://ai-api.jiapi.com。不要写成控制台地址，也不要在末尾追加 /chat/completions。
二、Codex UI 客户端
UI 客户端适合第一次使用 Codex 的新手。它有图形界面，支持 Windows 和 macOS，配置时也更容易观察是否已经登录、是否启动成功、是否需要完全退出重启。
适合 Windows 桌面用户。
适合 macOS 桌面用户。
三、Codex CLI
CLI 适合终端用户、远程开发、WSL、Linux 服务器和自动化场景。CLI 的重点不是图形界面，而是能在项目目录中运行 codex 命令。
CLI 安装前先检查 Node.js
很多 CLI 安装方式依赖 Node.js/npm。新手先确认 Node.js 和 npm 可用：
node -v
npm -v如果命令不可用，先安装 Node.js LTS，然后重新打开 PowerShell。
node -v
npm -v如果命令不可用，先安装 Node.js LTS。服务器环境可以使用系统包管理器、nvm 或你的团队标准安装方式。
安装 Codex CLI
不同版本的 CLI 安装命令可能变化。核心目标只有一个：安装后执行 codex --version 能看到版本号。
如果你的安装说明要求 npm，可以按这种方式安装：
npm install -g @openai/codex
codex --version如果提示包名、权限或版本错误，以当前官方安装说明为准；但排查时仍然先确认 node -v、npm -v、codex --version。
如果你使用官方安装脚本，可以按系统执行：
Windows PowerShell：
irm https://chatgpt.com/codex/install.ps1 | iex
codex --versionmacOS / Linux / WSL：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --versionCLI 不等于 UI 客户端
UI 客户端和 CLI 可以共用用户级配置，但它们的启动方式不同。CLI 必须能在当前终端执行 codex 命令；UI 客户端能打开窗口，不代表 CLI 一定已经安装。
四、自动配置
如果你只是想尽快用起来，推荐先使用自动配置工具。
测试连接，确认 Base URL、API Key 和模型能连通。一键写入配置。
自动工具本质上做了什么？
自动配置工具本质上是帮你写入用户目录下的 auth.json 和 config.toml。如果自动工具不可用，可以继续看后面的“手动配置”章节。
五、手动配置
如果你不使用自动配置工具，或者想自己检查配置细节，可以按下面步骤手动完成。
配置目录和文件
UI 客户端和 CLI 都会读取用户级 Codex 配置。除非你主动设置 CODEX_HOME，默认目录通常如下：
C:\Users\你的用户名\.codex适合 Windows UI 客户端、PowerShell CLI、IDE 插件。
/Users/你的用户名/.codexFinder 默认隐藏点开头目录，建议用 Terminal 或客户端设置入口打开。
/home/你的用户名/.codex适合 Linux、WSL、服务器、远程终端和纯 CLI 用户。
.codex 文件夹。
~/.codex 找到配置文件。auth.json 配置
在 .codex 目录中创建或打开 auth.json，放入如下内容：
{"OPENAI_API_KEY": "your_api_key_here"}
API Key 易错点
键名必须是 OPENAI_API_KEY，不要删除引号，不要在 JSON 里添加注释，也不要把完整 API Key 截图发给别人。
config.toml 配置
在 .codex 目录中创建或打开 config.toml，把下面内容放到文件前面：
model_provider = "JiaPi"
model = "gpt-5.4"
model_reasoning_effort = "medium"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.JiaPi]
name = "JiaPi"
base_url = "https://ai-api.jiapi.com"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
config.toml 中的 provider 名称、模型和 Base URL 要互相对应。model_provider
告诉 Codex 使用下面定义的 JiaPi 服务商。
model
使用的模型名称，必须和 JiaPi 可用模型一致。
base_url
JiaPi 的 OpenAI 兼容接口地址。
env_key
告诉 Codex 从 OPENAI_API_KEY 环境变量中读取密钥。
不要整份覆盖旧配置
如果你已经有别的 Codex 配置，不要整份删除。只需要把 model_provider、model 和 [model_providers.JiaPi] 这一段合并进去。JiaPi provider、Base URL 和密钥相关设置应放在用户目录的 ~/.codex/config.toml 中，不建议写到项目目录里的 .codex/config.toml。
六、重启并验证
你好，请回复一句测试成功。先进入一个普通项目目录：
Windows PowerShell：
cd C:\path\to\your-project
codexmacOS / Linux / WSL：
cd ~/code/your-project
codex第一次任务建议输入：
请只阅读当前项目，不要修改任何文件。先说明这个项目的目录结构和技术栈。
七、常见问题
八、安全提醒
不要泄露 API Key
不要把完整 API Key 发到群聊、截图、工单、公开仓库或文档里。不要把 auth.json、.env、含密钥的 shell profile 提交到项目仓库。排查问题时可以只展示 API Key 前后少量字符，例如 sk-...abcd。