𝐗𝐀𝐈 𝐂𝐨𝐧𝐭𝐫𝐨𝐥

OpenAI Codex App 安装与配置上手指南（macOS / Windows）

Posted March 4, 2026 by XAI 技术团队 ‐ 7 min read

这篇文章基于 OpenAI 官方文档整理，目标是让普通用户在最短时间内完成 Codex App 的安装和配置。 文中信息对应官方文档检查日期：2026-03-05。

先看结论（1 分钟版）

  1. macOS：直接下载安装包（.dmg），按本文配置后即可使用。
  2. Windows：从 Microsoft Store 安装，默认可用 PowerShell；如你主要在 Linux 工具链开发，可切换到 WSL Agent。
  3. 配置文件：核心在 ~/.codex/config.toml，你可以用全局配置 + 项目级 .codex/config.toml 组合管理。
  4. 推荐方式：先配置 ~/.codex/config.toml + XAI_API_KEY，然后直接打开项目使用；未配置时再走 App 内登录流程。

官方支持与账号要求

根据官方 Codex App 文档：

  1. Codex App 支持 macOS（Apple Silicon） 与 Windows。
  2. ChatGPT Plus / Pro / Business / Edu / Enterprise 计划包含 Codex 能力。

一、macOS 安装与首次使用

1）下载并安装

官方 macOS 下载链接：

下载后双击安装，按系统提示拖入 Applications。

2）打开 App（推荐：配置后直接用）

如果你已经按本文配置好 ~/.codex/config.toml，并且设置了 XAI_API_KEY，通常可直接进入项目开始使用，不需要再在 App 里单独选择登录方式。

仅在你没有配置自定义 Provider 或 Key 时，再按官方流程使用 ChatGPT 账号或 OpenAI API Key 登录。

3）选择项目目录

首次进入后，选择你要操作的代码目录。

4）发送第一条消息

进入项目后，先保持 Local 目标模式，直接发起任务，例如：

  • “先帮我解释一下这个仓库目录结构”
  • “帮我找出最近可能的错误点并给修复建议”
  • “为这个函数补充测试”

二、Windows 安装与首次使用

1）从 Microsoft Store 安装

官方 Windows 下载入口：

2）更新方式

官方建议通过 Microsoft Store 更新：

  1. 打开 Microsoft Store。
  2. 进入 Downloads。
  3. 点击 Check for updates。

3）默认运行模式

Windows 下默认是 Windows Native Agent：

  1. 命令默认在 PowerShell 环境执行。
  2. 使用 Windows sandbox。

4）切换到 WSL（可选，推荐给 Linux 开发流）

如果你主要依赖 Linux 工具链（如 bash、GNU 工具、Linux Node/Python 生态），可切换 Agent 到 WSL。

操作路径（官方文档）：

  1. 打开 Settings。
  2. 找到 Agent 运行模式。
  3. 从 Windows Native 切换到 WSL。
  4. 重启 App 使设置生效。

提示：Agent 与集成终端可独立配置。你可以 Agent 用 WSL、终端仍用 PowerShell，反之也可以。

三、配置文件 config.toml 快速理解

官方配置基础文档说明：

  1. 用户级配置文件：~/.codex/config.toml
  2. 项目级配置文件：<项目>/.codex/config.toml
  3. 优先级（高到低）：CLI 参数 > Profile > 项目配置 > 用户配置 > 系统配置 > 内置默认值

也就是说：你可以把通用偏好放在 ~/.codex/config.toml，项目特定覆盖放在仓库内 .codex/config.toml。

四、示例配置（可直接参考）

下面是一个可直接参考的示例：

model_provider = "xai"
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "detailed"
model_verbosity = "high"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.xai]
name = "xai"
base_url = "https://api.xairouter.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

关键字段解释

  1. model_provider / model：选择模型供应商与默认模型。
  2. approval_policy：是否每次高风险操作都要你确认。
  3. sandbox_mode：Codex 在本地命令执行时的权限边界。
  4. base_url：供应商 API 地址。
  5. env_key：读取哪个环境变量当作 API Key。

安全建议（普通用户推荐）

该示例配置偏高权限：

  • approval_policy = "never"
  • sandbox_mode = "danger-full-access"

如果你追求更稳妥，建议改为：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

五、环境变量设置（按示例中的 XAI_API_KEY）

因为示例使用了：

env_key = "XAI_API_KEY"

所以系统里必须有 XAI_API_KEY。

macOS / Linux

macOS 默认 shell 是 zsh，建议优先写入 ~/.zshrc：

echo 'export XAI_API_KEY="你的密钥"' >> ~/.zshrc
source ~/.zshrc

如果你在 Linux 的 bash 环境中使用，再写入 ~/.bashrc：

echo 'export XAI_API_KEY="你的密钥"' >> ~/.bashrc
source ~/.bashrc

Windows（PowerShell）

当前会话：

$env:XAI_API_KEY = "你的密钥"

持久化到用户环境变量：

setx XAI_API_KEY "你的密钥"

设置后重开终端/应用再生效。

六、常用设置（图形化）

1）默认 Open In 编辑器

你可以在设置中指定默认打开编辑器（VS Code / Visual Studio / 其他）。

2）集成终端

Windows 下常见可选：PowerShell、Command Prompt、Git Bash、WSL。

注意：切换终端后通常对新会话生效，必要时重启 App。

七、快速排错

1）PowerShell 执行策略报错

官方文档给出的常见修复是：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2）Windows 下 Git 功能不可用

先安装原生 Git：

winget install Git.Git

3）只想先验证环境是否可用

在 App 里执行这三类任务即可快速验证：

  1. “解释当前项目结构”
  2. “执行一条安全命令并解释输出（如 git status）”
  3. “修改一个小函数并生成变更说明”

官方文档与下载入口

  1. Codex App 总览：https://developers.openai.com/codex/app/
  2. Windows 专页：https://developers.openai.com/codex/app/windows/
  3. App 设置：https://developers.openai.com/codex/app/settings/
  4. 配置基础：https://developers.openai.com/codex/config-basic
  5. 认证与登录：https://developers.openai.com/codex/auth
  6. macOS 下载（官方）：https://persistent.oaistatic.com/codex-app-prod/Codex.dmg
  7. Windows 下载（官方商店）：https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US