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

头像
失落的生菜
     上海
    阅读 7 分钟
    发布日期：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、超时、配置不生效问题的排查。

    五种形态一览

    形态入口国内可用性认证方式适合场景
    CLInpm 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.comChatGPT 账号云端并行任务、直接创建 PR
    API/SDKdevelopers.openai.com/codex/sdk✅ 中转 API 可用API KeyCI/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 Siliconcodex-aarch64-apple-darwin.tar.gz
    macOS x86_64codex-x86_64-apple-darwin.tar.gz
    Linux x86_64codex-x86_64-unknown-linux-musl.tar.gz
    Linux arm64codex-aarch64-unknown-linux-musl.tar.gz
    WindowsPowerShell 安装脚本 / 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 Siliconhttps://persistent.oaistatic.com/codex-app-prod/Codex.dmg
    macOS Intelhttps://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg
    WindowsMicrosoft 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 InsidersVisual Studio Code Marketplace 搜索"Codex"
    CursorCursor 插件市场
    WindsurfWindsurf 插件市场
    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

    最常见原因（按频率）：

    1. auth.json 和 config.toml 同时有认证信息，产生冲突
      → 只保留一处，auth.json 只放 API Key，或只在环境变量里设置
    2. API Key 分组权限不足（中转服务常见）
      → 检查中转平台控制台，确认 Key 有 gpt-5.5 等目标模型的访问权限
    3. config.toml 放在项目目录但 model_provider 不生效
      → model_provider 必须写在 ~/.codex/config.toml（全局），不是项目级
    4. 修改配置后未重启
      → 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 插件安装后连不上

    1. 打开 VS Code 命令面板（⌘⇧P）→ 搜索"Codex: Sign In"
    2. 选择 API Key 认证方式，粘贴中转 API Key 和 base_url
    3. 如果卡在登录页，检查 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。

    参考来源：

    • Codex 官方文档（developers.openai.com/codex）
    • Codex CLI GitHub 仓库（github.com/openai/codex）
    • Codex 桌面版下载页（developers.openai.com/codex/app）
    • Codex IDE 扩展文档（developers.openai.com/codex/ide）
    • Fenno 官网：AI 编程
    人工智能教程openai编辑器
    失落的生菜
    1 声望0 粉丝
    « 上一篇
    Codex config.toml 应该怎么写？完整字段参考 + 场景配置示例
    下一篇 »
    Codex 额度限制怎么计算？5 小时窗口、周限额和解决办法

    引用和评论

    推荐阅读
    头像
    Codex 额度限制怎么计算？5 小时窗口、周限额和解决办法

    失落的生菜

    头像
    AI Agent中6种常用的设计模式

    苏三说技术赞 1阅读 5.6k

    头像
    OpenAI vs Anthropic vs Google：2026年AI大模型竞争格局

    ViVaAPI赞 1阅读 15.3k

    头像
    终结“定位漂移与盲盒”的玄学：玩透 HarmonyOS Web 组件的位置权限心法

    蓝胖子样样好阅读 32.2k

    头像
    HarmonyOS APP开发之玩透 ChannelConfig 的声道映射

    蓝胖子样样好阅读 32k

    头像
    HarmonyOS Wear Engine Kit API全解析：打通手机与腕间的“任督二脉”

    蓝胖子样样好阅读 31k评论 2

    头像
    HarmonyOS V2 状态管理之 `PersistenceV2`：让数据“起死回生”的艺术

    蓝胖子样样好阅读 30.5k

    0 条评论
    得票最新