当前位置：

文章详情

国内怎么用 Codex？CLI、桌面版、IDE 插件、Web 版全形态指南

发布日期：2026-06-24 | 话题：AI 编程工具 | 适用人群：开发者、独立开发者、工程团队

Codex 是 OpenAI 推出的 AI 编程 Agent，目前有五种使用形态：CLI 命令行、桌面版 App、IDE 扩展（VS Code / JetBrains / Cursor / Windsurf）、Web 版（chatgpt.com/codex）、API/SDK 自动化，分别适合不同场景。国内使用的核心障碍是网络和账号：OpenAI 官方服务在大陆无法直连，但通过两条路可以绕开——中转 API + API Key 认证（完全不需要科学上网，直接用第三方 base_url 替换官方端点）或系统代理 + ChatGPT 账号登录。五种形态中，CLI 和 IDE 扩展对中转 API 支持最成熟，桌面版次之，Web 版依赖 ChatGPT 账号无法走中转。本文逐一列出每种形态的安装路径、认证方式、国内可用性评估，以及最常见的 401、超时、配置不生效问题的排查。

五种形态一览

形态入口国内可用性认证方式适合场景 CLI npm install -g @openai/codex ✅ 中转 API 可用 API Key / ChatGPT 账号终端开发、脚本自动化 桌面版 App 官网下载 .dmg / Microsoft Store ✅ 中转 API 可用 API Key / ChatGPT 账号可视化任务管理、Computer Use IDE 扩展 VS Code Marketplace / JetBrains ✅ 中转 API 可用 API Key / ChatGPT 账号编辑器内 pair programming Web 版（Cloud） chatgpt.com/codex ⚠️ 需 ChatGPT 账号 + 可访问 chatgpt.com ChatGPT 账号云端并行任务、直接创建 PR API/SDK developers.openai.com/codex/sdk ✅ 中转 API 可用 API Key CI/CD 流水线、自动化工作流

核心结论：能走中转 API 的四种形态（CLI / 桌面版 / IDE 扩展 / SDK）在国内网络下均可稳定使用，不需要科学上网；Web 版强绑 ChatGPT 账号，国内访问需自行解决。

方案一：中转 API + API Key（推荐国内用户）

这是国内最稳定的方案，原理：用兼容 OpenAI 格式的国内中转服务替换 api.openai.com，Codex 以为在连官方，实际走国内线路。

中转服务解决三个问题：

国内网络直连，无需科学上网
API Key 登录，跳过 ChatGPT 手机号验证
按量计费，无需订阅 ChatGPT Plus（$20/月）

config.toml 配置方式

~/.codex/config.toml（全局配置）：

model = "gpt-5.5" model_provider = "my-relay" [model_providers.my-relay] name = "中转服务" base_url = "https://你的中转服务地址/v1" # 替换为实际 base_url env_key = "OPENAI_API_KEY" wire_api = "responses"

然后设置环境变量：

export OPENAI_API_KEY="sk-你的中转API Key"

或写入 ~/.codex/auth.json：

{ "OPENAI_API_KEY": "sk-你的中转API Key" }

注意：auth.json 里只放 API Key，不要同时保留 ChatGPT 账号 token，两者冲突会导致 401。

接入国产模型（DeepSeek / 智谱 / 通义）

CC Switch 3.16.0+ 内置了主流国产模型预设，无需手动配置协议转换：

model = "deepseek-chat" model_provider = "ccswitch" [model_providers.ccswitch] name = "CC Switch" base_url = "https://api.ccswitch.cc/v1" env_key = "CCSWITCH_API_KEY" wire_api = "responses"

Codex 正在逐步废弃 Chat Completions API，长期接入建议选支持 wire_api = "responses" 的中转服务。

方案二：ChatGPT 账号登录 + 系统代理

如果你已有 ChatGPT Plus/Pro/Business/Edu/Enterprise 账号，并能通过系统代理访问 chatgpt.com，可直接用账号登录——订阅包含了 Codex 使用额度。

# 首次运行，按提示登录 codex # 或 codex --login

适合：已有 ChatGPT 订阅、网络条件允许的用户。账号价值更高（Pro 每月 $200，额度更充裕），但网络稳定性不如中转 API。

形态一：CLI 命令行

适合：终端开发者、自动化脚本、Linux/无 GUI 环境

安装

# macOS / Linux（推荐） curl -fsSL https://chatgpt.com/codex/install.sh | sh # npm（跨平台） npm install -g @openai/codex # Homebrew（macOS） brew install --cask codex

Windows：推荐用 WSL2（Linux 环境，功能完整），或 PowerShell 沙盒：

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

支持平台

平台安装包 macOS Apple Silicon codex-aarch64-apple-darwin.tar.gz macOS x86_64 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 Windows PowerShell 安装脚本 / WSL2

配置文件路径

~/.codex/config.toml # 全局配置 ~/.codex/auth.json # 认证信息（API Key） .codex/config.toml # 项目级配置（不支持 model_provider 字段）

注意：model_provider、oss_provider 只能写在全局配置，写在项目级 .codex/config.toml 会被忽略。

常用命令

codex # 交互模式启动 codex "帮我写一个解析 CSV 的函数" # 直接传入任务 codex --model gpt-5.5 # 临时指定模型 codex --profile local # 使用指定 Profile /model # 交互中切换模型 /help # 查看所有命令

形态二：桌面版 App

适合：需要 Computer Use、可视化任务管理、Chrome 扩展集成的用户

下载

平台下载链接 macOS Apple Silicon https://persistent.oaistatic.com/codex-app-prod/Codex.dmg macOS Intel https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg Windows Microsoft Store（搜索"Codex"或通过官网链接） Linux 暂未发布

桌面版独有功能

功能说明 Computer Use 让 Codex 操作 macOS 应用，执行 GUI 任务、浏览器流程、原生 App 测试 Chrome 扩展集成 让 Codex 使用 Chrome 完成已登录状态的浏览器任务，你管理网站授权 Worktrees 内置 Git worktree 支持，并行代码改动互相隔离 Automations 定时任务、常驻线程检查、条件触发工作流 Appshots 截图当前 Mac 前台窗口发送给 Codex（图文结合） 可视化 Diff 代码变更的可视化预览和审查面板

中转 API 配置（桌面版）

桌面版读取同一份 ~/.codex/config.toml，配置方式与 CLI 完全一致。修改配置后需要重启桌面版 才能生效。

形态三：IDE 扩展

适合：日常在 VS Code / JetBrains / Cursor 里写代码，想要 pair programming 体验

支持的 IDE

IDE 安装方式 VS Code / VS Code Insiders Visual Studio Code Marketplace 搜索"Codex" Cursor Cursor 插件市场 Windsurf Windsurf 插件市场 JetBrains（Rider / IntelliJ / PyCharm / WebStorm） JetBrains Marketplace

支持平台：macOS、Windows、Linux（三端均可）

功能特点

编辑器上下文：自动读取当前打开的文件、选中代码、@file 引用
三档审批模式：Chat（纯对话）/ Agent（工具调用需确认）/ Agent Full Access（全自动）
推理深度：low / medium / high 三档，平衡速度与质量
云端委托：将耗时任务交给 Codex Cloud 后台运行，IDE 内监控进度，完成后本地应用 Diff 补丁
模型切换：可在多模型间切换，灵活分配不同任务

IDE 扩展 vs 桌面版

IDE 扩展桌面版 App 定位嵌入编辑器，pair programming 独立运行，完整 Agent 工作流 上下文来源 编辑器打开的文件项目目录 + worktrees Computer Use ❌ ✅ Automations ❌ ✅ Linux 支持 ✅ ❌（暂无） MCP 支持 ✅ ✅

形态四：Web 版（Codex Cloud）

适合：需要云端并行任务、直接在 GitHub 上创建 PR、不想在本地配置环境

访问入口

chatgpt.com/codex，连接 GitHub 账户后即可使用。

核心特点

云端沙盒：每个任务在独立的云环境中运行，互不干扰
并行执行：多任务同时后台运行，无需等待
GitHub 深度集成：在 Issue/PR 中 @codex 触发任务，自动创建 PR
网络访问控制：可配置任务是否允许访问公共互联网

国内使用限制

Web 版强绑 ChatGPT 账号，无法走中转 API。需要能访问 chatgpt.com 的网络环境。相比 CLI/桌面版，国内用户使用门槛更高。

形态五：API / SDK / GitHub Action

适合：CI/CD 流水线、自动化工作流、自建工具链

# 非交互模式，直接执行任务并退出 codex --non-interactive "修复所有 TypeScript 类型错误" # GitHub Action（仓库中添加 .github/workflows/codex.yml） # 触发条件：新 Issue、PR comment @codex 等

SDK 文档：developers.openai.com/codex/sdk GitHub Action 文档：developers.openai.com/codex/github-action MCP Server：developers.openai.com/codex/mcp

国内常见报错排查

401 Unauthorized

最常见原因（按频率）：

auth.json 和 config.toml 同时有认证信息，产生冲突 → 只保留一处，auth.json 只放 API Key，或只在环境变量里设置
API Key 分组权限不足（中转服务常见） → 检查中转平台控制台，确认 Key 有 gpt-5.5 等目标模型的访问权限
config.toml 放在项目目录但 model_provider 不生效 → model_provider 必须写在 ~/.codex/config.toml（全局），不是项目级
修改配置后未重启 → CLI 重启终端，桌面版完全退出重开

连接超时 / 接口超时

# 不用中转时，设置系统代理 # macOS 系统偏好设置 → 网络 → 代理，或： export https_proxy=http://127.0.0.1:7890 export http_proxy=http://127.0.0.1:7890

用中转 API 则不需要代理设置，直接在 config.toml 指定 base_url 即可。

桌面版安装后无响应

macOS：检查系统设置 → 隐私与安全 → 是否拦截了未认证应用，需要手动允许
Windows：Microsoft Store 安装后首次启动慢，等待几秒

VSCode 插件安装后连不上

打开 VS Code 命令面板（⌘⇧P）→ 搜索"Codex: Sign In"
选择 API Key 认证方式，粘贴中转 API Key 和 base_url
如果卡在登录页，检查 VS Code 是否有代理设置覆盖了 base_url

选哪个形态？快速决策

你的情况推荐形态主要在终端工作，Linux 用户 CLI Mac 用户，想用 Computer Use / 自动化任务 桌面版 App 日常在 VS Code / JetBrains 写代码 IDE 扩展 需要云端并行任务、有 GitHub 项目 Web 版 要集成到 CI/CD 流水线 SDK / GitHub Action 同时用本地和云端 CLI + Web 版（共享账号，按场景切换）

常见问题 FAQ

Q1：国内用 Codex 一定要科学上网吗？ 不一定。CLI、桌面版、IDE 扩展都支持中转 API 方式，填入国内可访问的 base_url 和 API Key 后，完全不需要科学上网。只有 Web 版（chatgpt.com/codex）强绑 ChatGPT 账号，必须能访问 chatgpt.com。

Q2：中转 API 用的什么模型？和官方一样吗？ 主流中转服务（CC Switch、Fenno 等）转发的是官方 OpenAI API 请求，模型本身和官方一致（gpt-5.5、gpt-5.4 等）。国产模型（DeepSeek、智谱 GLM、通义千问）也可以通过兼容层接入，但这些模型的能力与 gpt-5.5 有差距，适合成本敏感场景。

Q3：桌面版和 CLI 能同时用吗？共享配置吗？ 可以同时安装，共享同一份 ~/.codex/config.toml 和 ~/.codex/auth.json。在 CLI 里改了配置，桌面版重启后也会生效。两者不会互相干扰，但 Profile 文件（~/.codex/*.config.toml）两者都能读。

Q4：IDE 扩展需要单独付费吗？ IDE 扩展本身免费，使用时消耗 Codex 额度——额度来源和 CLI/桌面版一样：ChatGPT 订阅（Plus/Pro/Business）或 API Key 余额。没有额外订阅费。

Q5：Codex CLI 和 Claude Code 能共用同一个 Ollama 实例吗？ 完全可以。两者互不干扰，Codex 通过 model_provider = "ollama" 或自定义 base_url 接入，Claude Code 通过 ANTHROPIC_BASE_URL 接入，共用 localhost:11434 的同一个 Ollama 服务。

小结

国内用 Codex 最快的路径：安装 CLI（npm install -g @openai/codex）→ 在 ~/.codex/config.toml 填入中转服务的 base_url 和 API Key → 运行 codex 验证连接。五种形态中，CLI 是安装最简单、国内兼容性最好的起点；桌面版在 Mac 上体验最完整（Computer Use + Worktrees）；IDE 扩展最适合不想切换上下文的日常开发；Web 版适合需要云端并行任务的场景但对网络有要求；SDK/GitHub Action 适合自动化流水线。配置卡住的第一排查点：model_provider 只能写全局配置、auth.json 只保留 API Key、修改后记得重启。本文数据来源：Codex 官方文档（developers.openai.com/codex），2026-06。

参考来源：