Codex桌面版与CLI共存安装全攻略

这里为你整理了一份详细的 Codex 桌面版 + 命令行 (CLI) 共存安装与使用教程。遵循这份指南，你将完成所有步骤，并从零开始体验这两个强大的工具。

整个流程主要分为四个部分：

🔧 第一步：准备工作

在开始安装前，请确保满足以下条件：

💻 第二步：安装桌面版 (Desktop App) 与 CLI

这一步将指导你同时安装桌面版和命令行工具，并解决它们之间可能存在的配置冲突。

⌨️ 安装命令行工具 (CLI)

核心要求：你的系统中需要先安装好 Node.js，且版本在 18 或以上。建议使用 22 或更新的版本以获得最佳体验。

方法一：使用 npm (推荐)

方法二：使用安装脚本

• 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"

🔄 确保配置共存

桌面版和 CLI 默认会共享同一个配置目录 (~/.codex 或 %USERPROFILE%\\.codex)。为了让它们和谐共存，推荐 先使用 CLI 完成首次登录（见第三部分），这会自动生成配置目录。之后再安装桌面版，它就能直接识别这些配置了。这样能有效避免版本冲突等未知问题。

📥 安装桌面版 (Desktop App)

• Windows 用户：建议通过 Microsoft Store 搜索 “Codex” 安装，这是官方推荐的安装方式，能保证稳定性和更新。或者，从 https://chatgpt.com/zh-Hans-CN/codex/ 下载 Windows 版本的安装包。

• macOS 用户：

• 检查芯片类型：点击桌面左上角苹果图标，进入“关于本机”，查看“芯片”或“处理器”一栏以确定是 Apple 芯片 还是 Intel 芯片。

• 下载正确版本：访问 https://developers.openai.com/codex/app，并根据你的芯片类型下载对应的安装包。如果从 Mac App Store 下载，目前主要支持 Apple 芯片的 Mac。

• 安装流程：双击下载好的 .dmg (macOS) 或 .exe (Windows) 安装包，按屏幕提示将 Codex 拖入“应用程序”文件夹或完成安装向导即可。

🔑 第三步：登录与基础配置

安装完成后，我们需要配置账号，让 Codex “认识” 你。

🔐 登录你的账号

• 桌面版：首次启动时，会自动弹出浏览器窗口，引导你登录 OpenAI 账号。若未弹出，可能需要检查是否有弹窗被拦截。

• CLI 工具：

  • ChatGPT 订阅登录（推荐）：在终端中输入 codex 命令，根据提示选择 “Sign in with ChatGPT”，浏览器会引导你完成授权。

  • API Key 登录：适合自动化脚本。在终端中运行以下命令，将 YOUR_API_KEY 替换为你的实际 API Key：

    echo "YOUR_API_KEY" | codex login –with-api-key

    或者将 OPENAI_API_KEY 设置为系统环境变量。

⚙️ 配置 Codex

• 配置目录：Codex 的所有配置都存储在你的用户主目录下的 .codex 文件夹中。

  • Windows: C:\\Users\\<你的用户名>\\.codex

  • macOS/Linux: ~/.codex

• 核心配置文件 (config.toml)：这是 Codex 的总控制中心，决定了其行为方式。

  • 主要用途：

  • 选择模型：你可以在 config.toml 中指定默认的 AI 模型，例如 model = "gpt-5.5" 或 "gpt-5.4"。

  • 设置审批模式：控制 Codex 的操作权限。

    • Auto (默认)：在项目目录内可自动操作，范围外需审批。

    • Read-only：只读模式，AI 无法修改文件。

    • Full Access：完全访问，权限最高。

  • 管理 API Key：auth.json 文件用于存储你的 API Key 凭证，请务必妥善保管此文件，不要外泄。

• 设置中文界面：在桌面版应用中，可以通过 /settings 或设置菜单找到语言选项，切换为中文。

🚀 第四步：核心使用指南

配置好之后，就可以开启你的 Codex 探索之旅了。

💻 桌面版基础使用

• 核心概念：

  • 对话：在桌面版中，一个“对话”相当于一次临时的交互，类似于一个聊天窗口。你可以在左侧的“对话”区域，随时“新建对话”来处理新任务。

  • 项目：一个“项目”关联你本地的某个代码文件夹。当你需要 AI 深入理解并操作整个项目代码时，通过“项目”入口打开它，Codex 就能分析整个工程。

• 任务模式：

  • Local：直接在本地项目环境中执行，适合日常开发和快速改动。

  • Worktree：为任务创建独立的 Git worktree，适合需要进行较大规模、可能影响主项目的改动。

  • Cloud：在云端环境中执行任务，可将任务放到远端。

  • 新人建议：初期可以“小任务先用 Local，中大任务优先 Worktree”。

• 斜杠命令：在输入框键入 /，可以快速调用特定功能。

  • /search <关键词>：在项目中搜索相关代码或文档。

  • /run <命令>：在 Codex 环境中执行终端命令。

  • /review：让 Codex 审查你当前的代码变更。

⌨️ CLI 基础使用

• 启动会话：在终端进入你的项目目录，直接输入 codex 命令，即可启动一个交互式会话。

• 场景化命令示例：

  • 理解项目：/ 阅读这个项目的代码结构，解释它的主要功能。 / 分析一下 main.py 的逻辑。

  • 编写和修改代码：/ 帮我写一个 quick_sort 函数。 / 修改 utils.js，将所有的 var 改为 const 或 let。

  • 运行和调试：/run npm test：可以执行测试。/ 解释一下 app.js 第 10 行到第 20 行代码的作用。

• 内联命令：

  • /model：在会话中切换 AI 模型。

  • /permissions：查看或修改当前的审批模式。

• 项目指导文件 (AGENTS.md)：你可以在项目根目录下创建 AGENTS.md 文件，向 Codex 提供项目特定的风格指引或约束，让它的行为更符合你的预期。

🐛 第五步：常见问题 (Troubleshooting)

这里整理了一些可能遇到的问题及其解决方案。

• “Windows 上桌面版安装后打不开，或一闪而过”？ 这通常是因为缺少必要的运行库。请下载并安装 Visual C++ Redistributable 的最新版本。

• “登录时提示 Token exchange failed: status 403 Forbidden”？ 这个错误通常与网络有关，特别是在公司网络或使用了代理的情况下。可以尝试配置终端的环境变量：

  export HTTPS_PROXY=http://你的代理地址:端口

• “执行命令时提示 command not found: codex？” 这说明 Codex 的可执行文件目录没有添加到系统的 PATH 环境变量中。可以尝试以下步骤：

• 查找安装路径：确认 Codex 被安装在了哪里，通常是 ~/.local/bin/codex。

• 添加到 PATH：

  • macOS/Linux (zsh)：

    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

  • macOS/Linux (bash)：

    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

  • Windows (PowerShell)：

    $p = [Environment]::GetEnvironmentVariable('PATH','User')
    [Environment]::SetEnvironmentVariable('PATH', "$p;$env:USERPROFILE\\.local\\bin", 'User')

  完成后，重启终端，再次运行 codex –version 验证。

• “codex 命令卡住不动，或无法唤起浏览器登录”？ 这通常发生在没有图形界面的服务器或远程终端环境中。可以使用设备码登录方式：

  codex login –device-auth

• “我的 auth.json 配置出错了”？ 如果确认账号无误但仍然出现问题，可能是 auth.json 文件冲突。可以先安全备份 auth.json 和 config.toml 文件，然后删除 .codex 目录，重新运行 codex login 生成全新的配置。