Codex 安装与配置指南

斯坦SteinY

245人浏览 · 2026-08-05 21:23:09

斯坦SteinY · 2026-08-05 21:23:09 发布

title: Codex 安装与配置指南（OpenAI API 登录 + DeepSeek）
date: 2026-08-05
tags:

Codex
OpenAI
DeepSeek
CLI
AI工具
开发工具
个人工作流
aliases:
Codex安装与配置
Codex DeepSeek 配置
description: Codex CLI 安装、OpenAI API Key 登录以及接入 DeepSeek 模型的完整指南

Codex 安装与配置指南（OpenAI API 登录 + DeepSeek）

Codex 是 OpenAI 推出的 AI 编程助手，可以直接在终端（Codex CLI）、ChatGPT 桌面端、VS Code 插件（Codex IDE extension）里使用。CLI、桌面端和 IDE 插件共用同一份配置（~/.codex/config.toml），配置一次即可在所有形态生效。

本文基于 2026-08-05 的 OpenAI 官方文档和 DeepSeek 官方文档整理，覆盖三部分：安装 Codex CLI、使用 OpenAI API Key 登录、配置 DeepSeek 作为模型提供方。

一、安装 Codex CLI

前置要求

macOS、Linux 或 Windows 10+；
建议安装 Git（Codex 在 Git 仓库中工作体验最佳）；
使用 npm 方式安装时需要 Node.js 18+。

方式一：官方独立安装脚本（推荐）

macOS / Linux 终端执行：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell 执行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

更新时重新执行同样的命令即可。

方式二：npm

npm install -g @openai/codex

更新：

npm install -g @openai/codex

方式三：Homebrew（macOS）

brew install --cask codex

更新：

brew upgrade --cask codex

方式四：GitHub Releases 手动下载

到 openai/codex Releases 下载对应平台的压缩包：

平台	文件
macOS Apple Silicon	`codex-aarch64-apple-darwin.tar.gz`
macOS Intel	`codex-x86_64-apple-darwin.tar.gz`
Linux x86_64	`codex-x86_64-unknown-linux-musl.tar.gz`
Linux arm64	`codex-aarch64-unknown-linux-musl.tar.gz`

解压后把二进制重命名为 codex，放到 PATH 中的目录（如 /usr/local/bin）即可。

验证安装

codex --version
codex --help

二、Codex App（桌面客户端）

如果习惯在桌面窗口里使用 Codex（项目规划、代码修改、交互式工作），可以下载 OpenAI 官方桌面客户端 Codex App：

官方下载地址：https://chatgpt.com/zh-Hans-CN/codex/
支持 macOS 和 Windows；
也可以用命令行直接启动：codex app；
登录方式与 CLI 一致：支持 ChatGPT 账号登录或 API Key 登录，且与 CLI 共享缓存凭据；
与 Codex CLI 共用 ~/.codex/config.toml：DeepSeek 配置写一次，两端都生效，桌面端模型选择器显示「自定义」/「DeepSeek-V4-Flash」即代表 DeepSeek 生效；
切换登录方式或模型提供方后，需要重启桌面端才生效。

三、登录

Codex 支持两种登录方式：

登录方式	适用场景	计费
ChatGPT 账号登录	已订阅 ChatGPT Plus / Pro / Business / Edu / Enterprise	使用订阅额度
OpenAI API Key 登录（★★★推荐方式-网页端无登录的生成API Key即可进入）	按 API 用量付费，适合脚本、CI、自动化	按 OpenAI Platform 标准 API 价格

方式一：ChatGPT 账号登录

直接运行：

codex login

会自动打开浏览器完成 OAuth 登录。登录成功后凭据缓存在本地（默认 ~/.codex/auth.json，或系统钥匙串）。

无头服务器 / 远程环境浏览器打不开时，可用设备码登录（Beta）：

codex login --device-auth

方式二：OpenAI API Key 登录

到 platform.openai.com/api-keys 创建 API Key（sk- 开头）；
把 Key 通过标准输入传给 codex login：

printenv OPENAI_API_KEY | codex login --with-api-key

也可以先设置环境变量再执行（注意不要把 Key 明文留在 shell 历史里）：

export OPENAI_API_KEY="sk-xxxx"
printenv OPENAI_API_KEY | codex login --with-api-key

注意：使用 API Key 登录后，依赖 ChatGPT 工作区/云能力的部分功能（如 Codex cloud）不可用或受限；费用按 API 用量从 OpenAI Platform 账户扣费。

登录状态与登出

codex login status   # 查看当前登录方式，已登录时退出码为 0
codex logout         # 清除当前凭据

凭据存储与安全

默认凭据缓存在 ~/.codex/auth.json（明文，包含访问令牌），也可以改用系统钥匙串：

# ~/.codex/config.toml
cli_auth_credentials_store = "keyring"   # file | keyring | auto

安全提醒：不要把 auth.json 或 API Key 提交进 Git 仓库、粘贴到工单或聊天里，它等价于你的密码。

四、配置 DeepSeek

3.1 先了解现状（重要）

DeepSeek API 原生支持 OpenAI Responses API，Codex 通过 wire_api = "responses" 与 DeepSeek 通信；
目前（2026-08）仅 deepseek-v4-flash 支持接入 Codex，deepseek-v4-pro 预计 2026 年 8 月初支持；
配置一次，Codex CLI、ChatGPT 桌面端、VS Code 的 Codex 插件全部生效；
需要 Codex 版本较新（DeepSeek 官方 models.json 声明的最低版本为 0.144.0），请先升级 Codex。

3.2 前置准备

注册 DeepSeek Platform 并充值；
创建 API Key（sk- 开头）；
确认 ~/.codex 目录已存在（运行过至少一次 codex 即可）。

3.3 方式一：官方一键配置脚本（推荐）

macOS / Linux：

bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh)

Windows PowerShell：

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

脚本会自动完成：

备份原配置到 ~/.codex/backup-deepseek/，随时可还原；
生成模型目录文件 ~/.codex/models.json（声明 DeepSeek 模型的上下文窗口、推理档位、工具调用格式等元数据）；
修改 ~/.codex/config.toml，只改写必要字段并新增 [model_providers.deepseek] 配置段，保留你原有的 MCP、信任级别等配置；
写入前做 TOML / JSON 语法校验，失败则中止且不修改任何文件。

再次运行脚本，可以在菜单中选择切换模型（flash / pro），或选第 3 项恢复到安装前的默认配置。

3.4 方式二：手动配置

第 1 步：创建模型目录文件 `~/.codex/models.json`

Codex 需要知道 DeepSeek 模型的元数据（上下文窗口 1M、支持的推理档位 low / high / max、工具调用格式、最低客户端版本等），否则会出现 400 或静默报错。

完整 models.json 内容较长（包含 deepseek-v4-flash 与 deepseek-v4-pro 两个模型条目），请从 DeepSeek 官方文档页面获取：

DeepSeek 官方文档：接入 Codex

页面中有「点击展开 models.json 完整内容」的代码块，直接复制保存为 ~/.codex/models.json 即可。也可以直接运行 3.3 节的一键脚本自动生成，然后把脚本生成的 models.json 复制出来。

结构示意（字段会随官方更新，以官方文档为准）：

{
  "models": [
    {
      "slug": "deepseek-v4-flash",
      "context_window": 1048576,
      "max_context_window": 1048576,
      "display_name": "DeepSeek-V4-Flash",
      "supported_reasoning_levels": [
        { "effort": "low" },
        { "effort": "high" },
        { "effort": "max" }
      ],
      "minimal_client_version": "0.144.0",
      "apply_patch_tool_type": "freeform",
      "shell_type": "shell_command"
    }
  ]
}

第 2 步：编辑 `~/.codex/config.toml`

不存在则新建，添加以下内容（experimental_bearer_token 填入你的 DeepSeek API Key）：

model = "deepseek-v4-flash"
model_provider = "deepseek"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/models.json"

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "sk-你的DeepSeek-API-Key"

字段说明：

字段	作用
`model`	默认使用的模型
`model_provider`	使用的模型提供方，对应下方 `[model_providers.deepseek]` 的 id
`preferred_auth_method` / `forced_login_method`	使用 API Key 认证，跳过 ChatGPT 账号登录
`model_reasoning_effort`	推理强度，越高思考越深入、耗时越长
`model_catalog_json`	自定义模型目录文件（`models.json`）的路径
`[model_providers.deepseek].name`	模型提供方显示名称
`base_url`	DeepSeek API 地址
`wire_api`	通信协议，`"responses"` 表示 Responses API
`experimental_bearer_token`	你的 API Key，直接写在配置文件里

不想把 Key 明文写进配置文件的话，可以改用环境变量方式（Codex 官方更推荐）：
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"
然后在 shell 配置（~/.zshrc 等）里 export DEEPSEEK_API_KEY="sk-xxxx"。

3.5 验证是否生效

进入项目目录启动 Codex CLI：

cd /path/to/my-project
codex

启动信息中显示 model: deepseek-v4-flash 即为生效。ChatGPT 桌面端的模型选择器中显示「自定义」/「DeepSeek-V4-Flash」也代表生效。

非交互式使用同样生效：

codex exec "帮我解释这个项目"

3.6 注意事项

历史会话分组：切换提供方后，之前用 ChatGPT 订阅产生的会话可能“不见了”——它们没被删除，Codex 按登录方式分组存放会话记录。恢复原配置（如一键脚本菜单第 3 项）后即可看到原来的会话，此时 DeepSeek 的会话会被隐藏。切换后需重启桌面端才生效。
配置文件位置：model_providers、model_provider 等字段只认用户级 ~/.codex/config.toml，写在项目级 .codex/config.toml 里会被忽略（出于安全设计）。MCP、信任级别等可以放项目级。
API Key 安全：Key 直接写在 config.toml 里等价于明文密码，注意文件权限、不要提交进 Git；也可以使用 3.4 节的环境变量方式。
模型支持范围：目前仅 deepseek-v4-flash；等 deepseek-v4-pro 正式支持后，把 model 改成 deepseek-v4-pro 并更新 models.json 即可。