Codex Desktop 怎么安装：Windows、macOS 全平台完整教程（含 TaoToken 配置）

1. Codex Desktop 安装前必须搞清楚的几件事

Codex Desktop 是 OpenAI 推出的桌面端编码 Agent 应用，官方定位是「a focused desktop experience for working on Codex threads in parallel」，也就是让你在一个图形界面里同时跑多个 Codex 任务线程。它内置了 worktree 支持、自动化任务和 Git 集成，适合需要图形化多任务、GUI 测试、浏览器流程操作的开发者。如果你只是想在终端里跑编码 Agent，Codex CLI 更轻量；但如果你想要并行线程、内置浏览器、Computer use 这类图形化能力，桌面版才是正解。

平台支持情况先说清楚：macOS（Apple Silicon 和 Intel 都支持）和 Windows（原生运行，基于 PowerShell 和 Windows sandbox，不需要 WSL）可以装桌面版，Linux 目前没有桌面版，只能用 Codex CLI 替代。这个信息很关键，因为很多人一上来就问「Linux 怎么装 Codex Desktop」，答案是暂时装不了，别在那边折腾兼容层。

安装前你需要确认三件事。第一，你的系统架构：macOS 用户点左上角苹果菜单 →「关于本机」看芯片是 M 系列还是 Intel，这决定你下载哪个 dmg。第二，你打算用 ChatGPT 账户登录还是 API Key 登录：官方明确提示用 API Key 时部分功能可能不可用，完整功能建议用 ChatGPT 账户（Plus、Pro、Business、Edu、Enterprise 套餐都含 Codex）。第三，你是否需要 GitHub 集成：如果需要，得额外装 GitHub CLI 并跑gh auth login。

还有一个容易被忽略的点：桌面版和 CLI 共享同一个配置主目录。Windows 上是%USERPROFILE%\.codex，macOS/Linux 是~/.codex。MCP 服务器、模型等配置写在那个目录下的config.toml，桌面和命令行可以共用。这意味着你如果之前已经配过 Codex CLI，桌面版启动后能直接复用一部分配置，不用从零再来一遍。

国内开发者接入 Codex 生态时，模型通道的稳定性是个现实问题。TaoToken 提供统一的 API 通道，把 Key 和 Base URL 配好之后，Codex CLI 和桌面版都能走同一条链路，省得每个工具单独折腾。下面我会把安装流程和 TaoToken 配置串起来讲，你照着做就行。

2. Windows 用 winget 安装 Codex Desktop 与 Codex CLI 初始化

Windows 上的安装路径有两条：Microsoft Store 图形界面安装，或者 PowerShell 里一行 winget 命令搞定。我推荐 winget，因为可复制、可脚本化，出问题也好排查。

打开 PowerShell（普通权限即可，不需要管理员），运行：

winget install Codex -s msstore

这条命令的-s msstore指定从 Microsoft Store 源安装。执行后 winget 会拉取 Codex 包并自动完成安装。如果你更习惯图形界面，打开 Microsoft Store 搜索 Codex 点安装也一样。

装完桌面版之后，配套开发工具建议一并装上，尤其是你打算用 GitHub 集成或者跑 Node/Python 项目的话：

winget install --id Git.Git winget install --id OpenJS.NodeJS.LTS winget install --id Python.Python.3.14

Git 是 worktree 和版本控制的基础，Node LTS 是很多 MCP 服务器和工具链的运行时，Python 3.14 则是不少 Agent 脚本的依赖。这三个装完，后面配 MCP 或者跑自动化任务会顺很多。

如果你还需要 GitHub 集成，再补一步：

winget install --id GitHub.cli gh auth login

gh auth login会走交互式认证，按提示选 GitHub.com、选 HTTPS、浏览器授权即可。

接下来是 Codex CLI 的初始化。桌面版和 CLI 可以共存，CLI 在排障和脚本化场景下很有用。Windows PowerShell 安装 CLI：

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

或者用 npm 全局安装（前提是 Node 已装好）：

npm install -g @openai/codex

装完运行codex，首次会提示你选择认证方式。选Sign in with ChatGPT走账户登录，或者按提示配置 API Key。这里就是接入 TaoToken 统一通道的切入点：你可以把 Base URL 指向 TaoToken 的 API 地址，Key 用 TaoToken 生成的 Key，这样 CLI 和桌面版都能走同一条模型通道。

Windows 配置文件位于%USERPROFILE%\.codex，进去之后你会看到config.toml。这个文件是桌面版和 CLI 共用的，MCP 服务器、模型配置都写这里。建议装完先确认这个目录存在，后面配 TaoToken 和 MCP 都靠它。

关于 WSL：不需要。Codex Desktop 在 Windows 上默认以原生 Windows Agent（运行 PowerShell）方式工作，WSL2 是设置里的可选项而非必需。注意自 Codex 0.115 版本起 WSL1 已不受支持，如果你确实想切 WSL，必须用 WSL2，切换后需要重启应用。

3. TaoToken 统一 Key 与 config.toml 可复制配置

这一节是整篇的核心操作部分。Codex Desktop 和 Codex CLI 共享~/.codex（Windows 是%USERPROFILE%\.codex）下的config.toml，所以你把 TaoToken 的通道配一次，两边都能用。

先拿 Key。打开 TaoToken 控制台创建 API Key，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。创建后复制那串 Key，注意别泄露，后面配置里要用。

然后编辑config.toml。Windows 路径：

# %USERPROFILE%\.codex\config.toml model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "responses"

macOS/Linux 路径是~/.codex/config.toml，内容一样。这里几个字段解释一下：model是你默认调用的模型 ID，按你实际需要的填；model_provider指向下面定义的 provider 名；base_url固定为https://taotoken.net/api（注意 API 地址不加 UTM 参数）；env_key指定从哪个环境变量读 Key；wire_api按 Codex 的要求填responses。

环境变量设置。Windows PowerShell：

setx TAOTOKEN_API_KEY "你的TaoToken Key"

macOS/Linux 写进 shell 配置：

export TAOTOKEN_API_KEY="你的TaoToken Key"

写到~/.zshrc或~/.bashrc里，然后source一下。注意setx设置后需要重开终端才生效。

如果你用的是 Codex CLI 并且习惯用auth.json管理凭据，可以在~/.codex/auth.json里配置。但更推荐用环境变量方式，因为桌面版和 CLI 都能读到，不用维护两份。

三件套对照表，配的时候对着检查：

配完之后，桌面版首次启动时选择项目文件夹，选 Local 模式让 Codex 在本机运行。如果你之前已经用 ChatGPT 账户登录过，桌面版可能会优先走账户认证；想强制走 TaoToken 通道，确认config.toml里的model_provider指向taotoken即可。

一个实操细节：config.toml里如果同时存在多个 provider，Codex 会按model_provider字段选当前生效的那个。你可以保留官方 provider 作为备选，把 TaoToken 设为默认，切换时只改一行。

4. 验证安装成功与请求测试的具体检查动作

装完不验证等于没装。这一节给你一套可执行的检查动作，从 CLI 到桌面版逐层确认。

第一步，确认 CLI 装好了。终端运行：

codex --version

能打印版本号说明二进制在 PATH 里。如果提示 command not found，Windows 检查 npm 全局路径是否在 PATH，macOS 检查/usr/local/bin或 Homebrew 路径。

第二步，确认配置读到了。运行：

codex config get model_provider

如果返回taotoken，说明config.toml被正确解析。返回空或者报错，检查文件路径和 TOML 语法，常见问题是缩进或引号写错。

第三步，发一个最小请求验证通道。在 CLI 里跑一个简单 prompt：

codex exec "用一句话说明什么是 worktree"

如果返回了模型输出，说明 Base URL、Key、Model ID 三件套都通了。如果报 401，往下看第五节排障。

第四步，桌面版启动检查。打开 Codex Desktop，选择项目文件夹，选 Local 模式。界面正常加载、能看到线程面板，说明桌面端初始化完成。新建一个线程发条消息，观察是否有响应。

第五步，确认配置目录共享。在桌面版里改一个设置（比如切换模型），然后去看~/.codex/config.toml是否同步变化。共享目录意味着你在 CLI 里配的 MCP 服务器，桌面版也能用。

第六步，如果你配了 MCP，验证 MCP 服务器加载：

codex mcp list

能列出你配置的服务器说明 MCP 配置生效。这一步在接 Cline MCP 或者 CC Switch 场景下特别有用。

实测下来，最容易出问题的是环境变量没生效。setx之后必须重开终端，macOS 的export必须写进 shell 配置文件而不是只在当前会话执行。验证环境变量：

echo $TAOTOKEN_API_KEY

Windows PowerShell 用echo $env:TAOTOKEN_API_KEY。能打印出 Key（注意别在公开场合贴出来）就说明注入成功。

5. 安装与接入常见报错排查

这一节按真实报错来，你遇到哪个对哪个。

401 Unauthorized。这是最常见的。原因通常是 Key 没读到或者 Key 无效。检查顺序：先echo $TAOTOKEN_API_KEY确认环境变量有值；再确认config.toml里env_key字段拼写和实际环境变量名完全一致（大小写敏感）；最后去 TaoToken 控制台确认 Key 没过期、没被删。如果用的是auth.json方式，检查 JSON 格式是否合法，多一个逗号都会导致解析失败。

local proxy failed / connection refused。这个报错说明 Codex 尝试连本地代理但连不上。如果你没配代理，检查config.toml里是不是残留了http_proxy之类的字段。如果你确实需要走代理，确认代理进程在跑、端口对。注意 Base URL 必须是https://taotoken.net/api，写成别的地址会直接连不上。

reading choices: unexpected end of JSON input。这个通常出现在流式响应解析阶段，原因可能是 Base URL 指向了一个不兼容responseswire API 的端点。确认wire_api = "responses"和 TaoToken 的 API 地址匹配。如果换了别的 provider，wire_api 字段要跟着改。

OAuth 相关报错。如果你用 ChatGPT 账户登录桌面版，遇到 OAuth 回调失败，检查默认浏览器是否能正常打开、有没有被安全软件拦截回调端口。这种情况可以改用 API Key 方式登录绕过 OAuth，但注意官方提示 API Key 模式下部分功能不可用。

winget install Codex -s msstore 失败。常见原因是 Microsoft Store 源没启用或者网络问题。先跑winget source list确认 msstore 源存在，没有的话winget source add msstore。如果还是失败，改用 Microsoft Store 图形界面搜索安装。

Codex CLI 装完 command not found。npm 全局安装的话，检查npm config get prefix输出的路径是否在 PATH 里。Windows 上通常是%APPDATA%\npm，macOS 是/usr/local/bin或 Homebrew 的/opt/homebrew/bin。

桌面版启动后一直转圈。检查~/.codex/config.toml是否有语法错误导致解析卡住。临时把文件重命名成config.toml.bak再启动，如果能起来说明是配置问题，逐段加回去定位。

MCP 服务器加载失败。如果你配了 Cline MCP 或 CC Switch，确认三件套（Base URL、Key、Model ID）都填了。MCP 服务器本身如果依赖 Node，确认 Node LTS 装好了。codex mcp list看不到服务器的话，检查config.toml里[mcp_servers]段的格式。

排障时有个通用思路：先用 CLI 验证通道（codex exec），CLI 通了再查桌面版。因为 CLI 的报错信息更直接，桌面版图形界面会吞掉一部分细节。

6. 装完之后怎么用起来

安装只是起点。Codex Desktop 的差异化能力在图形界面里：并行线程让你同时跑多个任务，内置浏览器可以打开渲染页面留评论或者让 Codex 操作本地浏览器流程，Computer use 能让 Codex 使用 macOS 应用完成 GUI 任务和原生应用测试，Appshots 把最前方的 Mac 应用窗口连同截图和可读文本一起发给 Codex。这些是 CLI 给不了的。

如果你主要做长期编码或者 Agent 编排，建议把 TaoToken 的 Coding Plan 用起来，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它适合需要稳定模型通道、频繁调用、多工具共存的场景，比按次计费更划算。

想先试试模型对话效果，可以直接开 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 对比不同模型在编码任务上的表现，再决定config.toml里默认用哪个 Model ID。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各工具的详细配置示例，包括 Claude Code 和 Anthropic 兼容接口的接法。如果你用 Claude Code 做润色或者代码审查，参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_anthropic&utm_campaign=rewrite 的配置方式，Base URL 和 Key 的填法逻辑和 Codex 是一致的。

最后提醒一个实操经验：config.toml改完不需要重启系统，但桌面版可能需要重启应用才能重新读取配置。CLI 每次调用都会重新读，所以改完直接跑codex exec就能验证。把配置版本化管起来（比如放进 dotfiles 仓库），换机器的时候直接拉下来，省得每次重配。