Codex 全网最全指南：安装、登录、国内登录问题解决、第三方模型配置、Skills 与桌面插件

OpenAI Codex 是 OpenAI 在 2025 年推出、2026 年全面升级的 AI 编程 Agent，提供本地 CLI、VS Code 扩展、Cursor/Windsurf 集成和桌面应用四种使用形态，核心能力是在终端中自主完成代码编写、修改、执行 Shell 命令、搜索文件和抓取网页等完整工程任务。Codex CLI 已在 GitHub 完整开源（openai/codex，Apache-2.0），支持 ChatGPT 订阅登录和 API Key 两种认证方式，并通过 config.toml 支持接入任意 OpenAI 兼容的第三方推理后端。本文覆盖 Codex 的完整使用路径：四种安装方式、两种登录方式、国内用户如何绕过桌面端 OAuth 登录障碍（手动 auth.json / Codex++ / CC Switch 三种方案对比，明确哪个能用插件）、通过 config.toml / CC Switch / Codex++ 三种手段接入第三方模型、Skills 系统（安装路径、SKILL.md 规范、内置技能、推荐社区技能）、桌面端插件体系（Skills/连接器/MCP/浏览器扩展），以及 AGENTS.md 配置和常用命令速查。

一、安装 Codex

Codex CLI 支持四种安装方式，按场景选择最合适的一种。

方式 A：官方安装脚本（推荐，无需 Node.js）

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"

脚本自动下载最新版、校验 checksum，并将 codex 命令加入 PATH。

方式 B：npm

npm install -g @openai/codex

要求 Node.js，适合已有 Node 环境的开发者。安装后升级：

npm install -g @openai/codex@latest

方式 C：Homebrew（macOS）

brew install --cask codex

适合 macOS 用户，更新由 Homebrew 统一管理。

方式 D：二进制直接下载

从 GitHub Releases（github.com/openai/codex/releases/latest）下载对应平台的压缩包：

解压后将可执行文件重命名为 codex 并放入 PATH 即可。

验证安装：

codex --version

二、登录与认证

方式一：Sign in with ChatGPT（订阅认证）

适合已有 ChatGPT Plus / Pro / Business / Edu / Enterprise 套餐的用户，在订阅额度内使用 Codex，无额外按量计费。

codex login

执行后自动打开浏览器，完成 OAuth 授权。凭据缓存在 ~/.codex/auth.json（等同密码，不要提交到 Git）。

查看当前登录状态：

codex login status

退出登录：

codex logout

无头设备（服务器/CI）：

codex login --device-auth   # 设备码流程（beta，需在设置中启用）

或者将本地 ~/.codex/auth.json 复制到远程机器，或通过 SSH 转发 localhost:1455 回调端口完成授权。

方式二：API Key 登录（按量计费）

适合不使用 ChatGPT 订阅、需要在 CI/CD 中编程化调用的场景。

从 OpenAI Dashboard 获取 API Key 后：

# 推荐方式（不暴露密钥在 shell history）
printenv OPENAI_API_KEY | codex login --with-api-key

# 或直接传入（注意 shell history 泄露风险）
echo "sk-xxxxx" | codex login --with-api-key

企业 Access Token：

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

三、国内用户：解决桌面端登录问题（核心痛点）

Codex 桌面应用和 CLI 的默认登录流程需要 ChatGPT Plus / Pro 账号，登录时通过 OAuth 连接 OpenAI 服务器完成授权。国内网络环境下这个 OAuth 流程不可直接访问，导致桌面端打开后卡在登录页、CLI 执行 codex login 后浏览器无法完成回调。

这一节专门讲三种绕过方案，按实际需求选一种。

方案对比速览

方案 A：手动配置 auth.json（最轻量）

原理：Codex 优先读取 ~/.codex/auth.json 和 ~/.codex/config.toml 里的凭据，直接把第三方 API Key 写入这两个文件，完全绕过 OAuth 流程。

步骤：

第一步：备份现有配置

cp ~/.codex/config.toml ~/.codex/config.toml.backup
cp ~/.codex/auth.json  ~/.codex/auth.json.backup

第二步：编辑 config.toml，添加供应商

以 Fenno（api.fenno.ai，统一 AI 网关，一个 API Key 聚合多款主流模型）为例，其官方 Codex 配置模板如下：

# ~/.codex/config.toml
model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.fenno.ai"
wire_api = "responses"
requires_openai_auth = true

轻量任务可将 model 改为 gpt-5.4 或 gpt-5.4-mini 降低消耗。其他支持 OpenAI Responses API 的供应商替换 base_url 即可；只支持 Chat Completions 的供应商把 wire_api 改为 "chat" 并添加 requires_openai_auth = false。

第三步：修改 auth.json，写入 API Key

打开 ~/.codex/auth.json，将 OPENAI_API_KEY 字段替换为你的 API Key（以 Fenno 为例）：

{
  "OPENAI_API_KEY": "<你的 Fenno API Key>"
}

第四步：重启 Codex

macOS 需要彻底退出 Codex.app 后从终端重新打开：

pkill -f Codex          # 强制退出
open -a Codex           # 重新打开

Windows 在任务管理器结束 Codex 进程后重新启动。

验证：先跑一个只读任务（如 "列出当前目录文件"），确认能正常响应后再执行写操作。

注意：此方案下 Codex 桌面端 Plugins 插件功能不可用（插件认证依赖 ChatGPT 官方登录态）。如果需要插件，使用方案 B。

方案 B：Codex++（桌面端最完整方案）

原理：通过 CDP（Chromium DevTools Protocol）注入脚本到运行中的 Codex 桌面应用，拦截并替换网络请求目标，无需修改 app.asar，支持插件和所有桌面功能。

步骤：

第一步：下载并安装两个包

从 github.com/BigPizzaV3/CodexPlusPlus/releases 下载：

• Codex++ 管理工具（用于配置供应商）
• Codex++（实际启动入口）

macOS 可能提示未知来源，进入「系统设置 → 隐私与安全性」找到对应提示，点击「仍要打开」。

第二步：在管理工具中添加供应商

打开 Codex++ 管理工具 → 供应商配置 → 添加供应商：

• 接入方式：纯 API
• Base URL：你的服务商地址（如 https://api.moonshot.ai/v1）
• API Key：你的密钥
• 模型列表：从上游获取或手动填写

第三步：必须从 Codex++ 入口启动

不要点原版 Codex.app，改用 Codex++ 图标启动，Codex++ 会自动加载注入脚本和你配置的供应商。

验证：在 Codex 桌面应用的设置页面确认模型已切换到你配置的供应商。

注意：Codex 官方更新后，Codex++ 的注入脚本可能短暂失效，等 Codex++ 发布更新版本即可。回滚方案：在管理工具中清除 API 模式，恢复原版登录。

方案 C：CC Switch（CLI 为主，多供应商管理）

CC Switch 最新版已支持 Codex 的第三方供应商切换，适合同时使用 Claude Code、Codex、Gemini CLI 等多工具的开发者。

CC Switch 与 Codex 桌面端的历史 bug：早期版本存在"Codex 不走 CC Switch 选的供应商"的问题（GitHub Issue #3073），官方已在新版修复。使用前建议保持 CC Switch 为最新版本。

步骤：

1. 安装 CC Switch（见本文第三章）
2. 打开 CC Switch → Add Provider → 填入你的第三方服务商的 API Key 和 Base URL
3. 在工具列表中启用 Codex，设置为默认供应商
4. 重启终端后执行 codex 验证

局限：CC Switch 方案不支持 Codex 桌面端的 Plugins 插件功能，使用体验等同于手动配置，适合 CLI 工作流。

常见报错速查

四、接入第三方模型

手段一：config.toml 直接配置（原生方案）

Codex CLI 在 ~/.codex/config.toml 中通过 [model_providers.<id>] 表支持任意 OpenAI 兼容 API。

完整配置模板（以 Kimi K3 为例）：

# 设置默认模型和供应商
model = "kimi-k3"
model_provider = "kimi"

# Kimi 供应商配置
[model_providers.kimi]
name = "Kimi (Moonshot AI)"
base_url = "https://api.moonshot.ai/v1"
env_key = "KIMI_API_KEY"       # 运行时从此环境变量读取密钥
wire_api = "chat"              # 第三方 Chat Completions 兼容 API 填 "chat"
requires_openai_auth = false   # 不强制 sk- 前缀校验

也可以接入统一 AI 网关（如 Fenno），一个 Key 切换多款模型，免单独维护多个供应商账号：

# Fenno 统一网关示例（支持 Responses API，参见 api.fenno.ai）
model_provider = "OpenAI"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
model_context_window = 1000000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.fenno.ai"
wire_api = "responses"
requires_openai_auth = true

在终端中导出 API Key（不要写入 TOML）：

export KIMI_API_KEY="sk-your-key-here"
codex "帮我检查这段代码的内存泄漏"

多供应商共存（DeepSeek + Kimi 同时配置）：

# 按需切换
[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.ai/v1"
env_key = "KIMI_API_KEY"
wire_api = "chat"
requires_openai_auth = false

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "chat"
requires_openai_auth = false

命令行临时切换供应商：

codex --config model_provider=kimi --model kimi-k3 "重构这个函数"
codex --config model_provider=deepseek --model deepseek-chat "写单元测试"

常见配置错误排查：

七牛云 AI 平台也支持 OpenAI 兼容 API，可将 base_url 指向七牛云 API 端点，一个 API Key 统一接入多款主流大模型。配置方式参见 七牛云 AI 编程工具配置大全（developer.qiniu.com/aitokenapi/13195/AI-Coding）。

手段二：CC Switch 一键管理（推荐多工具用户）

CC Switch（ccswitch.io，118,979 ★）是跨平台 AI CLI 统一管理工具，支持 Claude Code、Codex、Gemini CLI、OpenClaw 等 8 款工具，包含 50+ 供应商预设，配置一次全部工具同步生效。

安装与快速上手：

1. 从 github.com/farion1231/cc-switch/releases 下载对应平台安装包（macOS 已通过 Apple 公证）
2. 打开 CC Switch → Add Provider → 从预设列表选择供应商或填入自定义 API Key
3. 点击 Enable，重启终端后 Codex 即切换到新供应商

核心优势：

• 热切换：Claude Code 无需重启，Codex 等工具重启终端生效
• 本地代理 + 故障转移：自动熔断、健康检测，主供应商不可用时自动切换备用
• MCP 统一管理面板：Codex、Claude Code、Gemini CLI 的 MCP 服务器统一配置、双向同步
• 用量看板：按供应商/模型/时间段追踪 token 消耗和费用
• 云配置同步：支持 Dropbox / OneDrive / iCloud / NAS / WebDAV，多设备同步

手段三：Codex++（深度增强桌面体验）

Codex++（github.com/BigPizzaV3/CodexPlusPlus，25,831 ★）是专为 OpenAI Codex 桌面应用打造的外部增强工具，通过 CDP（Chromium DevTools Protocol）无侵入式注入，不修改官方 app.asar。

安装：

从 github.com/BigPizzaV3/CodexPlusPlus/releases 下载：

• Windows：CodexPlusPlus-*-windows-x64-setup.exe
• macOS Intel：CodexPlusPlus-*-macos-x64.dmg
• macOS Apple Silicon：CodexPlusPlus-*-macos-arm64.dmg

安装后有两个入口：

• Codex++：静默启动官方桌面应用，自动加载已保存供应商配置
• Codex++ 管理工具：配置供应商、模型、插件、会话、更新和诊断

适用场景：以 Codex 桌面应用为主要工作界面，需要自定义推理后端和 UI 增强的用户。

CC Switch vs Codex++ 选哪个：使用 2+ 款 AI 编程工具 → CC Switch；仅用 Codex 桌面应用 → Codex++ 更精准。两者可同时安装，不冲突。

四、Skills：Codex 的技能扩展系统

Skills 是什么？

Skills 是 Codex 的任务扩展机制——一个 Skill 就是一个目录，包含 SKILL.md（必填）和可选的脚本、文档、资产文件。Codex 启动时扫描 Skills 目录，按需加载；任务描述与 Skill 的 description 匹配时自动激活，也可以用 $skill-name 显式调用。

SKILL.md 文件格式

---
name: my-skill
description: 什么时候应该触发这个技能，什么时候不应该触发。
---

（技能的完整执行指令，支持 Markdown 格式）

Skills 安装路径与优先级

内置 Skills

安装 Skills

方式 A：内置 skill-installer（最简单）

$skill-installer graphify
$skill-installer code-review

方式 B：手动克隆或下载

# 安装到用户全局
git clone https://github.com/xxx/my-skill ~/.agents/skills/my-skill

# 或解压 ZIP 到 Skills 目录
unzip my-skill.zip -d ~/.agents/skills/

方式 C：CC Switch 一键安装（最方便）

CC Switch 的 Skills 面板支持从 GitHub 仓库 URL 或 ZIP 文件一键安装，同步到所有已启用的 AI 工具。

推荐 Skills 清单

官方仓库（openai/codex .codex/skills/ 目录）：

社区热门（ClawHub / GitHub）：

启用 / 禁用 Skills

在 ~/.codex/config.toml 中配置：

[[skills.config]]
path = "~/.agents/skills/my-skill"
enabled = false   # 临时禁用，重启 Codex 生效

五、插件（桌面端）

插件类型

桌面端 Codex 支持以下五种插件组件，一个插件可包含其中一项或多项：

安装插件

1. 打开 Codex 桌面应用，选择 Plugins 菜单（Work mode 或 Codex 模式下可见）
2. 搜索或浏览插件 → 点击 + 按钮安装
3. 连接器类插件按提示完成 OAuth 认证（可在安装时或首次使用时触发）
4. 新建对话后，直接描述任务（Codex 自动选择工具）或用 @plugin-name 显式指定

推荐插件

支持范围

• ✅ 桌面应用（Work mode 和 Codex 模式）
• ✅ Web 版（Work mode）
• ✅ Codex CLI
• ❌ Chat mode（不支持）
• ❌ IDE 扩展（不支持）
• ❌ 移动端（不支持）

卸载插件

在 Plugin browser 中找到已安装插件 → Uninstall plugin。注意：卸载后连接器的 OAuth 授权不会自动撤销，如需彻底断开，需要前往对应服务（GitHub / Slack 等）的授权管理页面手动撤销。

六、AGENTS.md：给 Codex 的项目说明书

AGENTS.md 是 Codex 在每次会话中自动读取的指令文件，用于告诉 Codex 你的技术栈、编码规范、禁止事项和项目特殊说明。

加载顺序（优先级从高到低）：

1. 项目根目录 AGENTS.md（仓库级，优先级最高）
2. ~/.codex/AGENTS.md（用户全局）
3. /etc/codex/AGENTS.md（管理员下发，企业场景）

基础模板：

# 项目说明

## 技术栈
- 语言：Python 3.12 + TypeScript 5.x
- 框架：FastAPI + React
- 包管理：uv（Python）/ pnpm（前端）

## 编码规范
- Python 函数不超过 50 行
- 所有公共函数必须有 docstring
- 提交信息遵循 Conventional Commits

## 测试
- 单元测试用 pytest，不用 mock，直接跑真实数据库
- 每次修改后运行 `just test` 而不是 `pytest` 直接运行

## 禁止事项
- 不要修改 `config/production.toml`
- 不要删除 migrations 目录中的任何文件
- 不要向 git 提交 .env 文件

实用技巧：

• 把常见报错和对应修复方案写进 AGENTS.md，避免 Codex 每次重复走弯路
• 如果某个目录里有大量自动生成文件（如 dist/、node_modules/），在 AGENTS.md 中明确标注"不要修改此目录"
• 团队共用时，将 AGENTS.md 提交到 Git，让所有成员（和 AI）保持同一理解

七、常用命令速查

CLI 基础命令

codex                      # 进入交互模式
codex "任务描述"             # 单条任务
codex -p "任务"             # 等同上一条
codex -c                   # 继续上次会话
codex --model kimi-k3 "任务"              # 临时指定模型
codex --config model_provider=kimi "任务" # 临时指定供应商

CLI 内斜杠命令

快捷键

关键文件位置

小结

Codex 的使用路径从安装到进阶可以概括为四步：安装并登录 → 按需接入第三方推理后端（config.toml 原生配置 / CC Switch 一键管理 / Codex++ 桌面增强）→ 通过 Skills 扩展任务能力（内置技能 + 社区技能 + 自定义 SKILL.md）→ 用桌面插件打通外部工具生态（GitHub / Slack / MCP / 浏览器扩展）。AGENTS.md 是贯穿始终的"说明书"，写好它能让 Codex 在每个项目中都表现得更准确。

参考资料

• OpenAI Codex 官方仓库：github.com/openai/codex（Apache-2.0 开源）
• Codex 官方文档：learn.chatgpt.com/docs
• CC Switch 官方网站：ccswitch.io
• Codex++ 官方仓库：github.com/BigPizzaV3/CodexPlusPlus
• 七牛云 AI 编程工具配置大全：https://www.qiniu.com/ai/plan

数据截止：2026 年 7 月 20 日，Codex CLI 持续迭代，请以 GitHub Releases 和官方文档为准。