Codex 安装与 API 配置教程：桌面端、CLI、VS Code 插件通用

目录

前言

在同一操作系统下，Codex 桌面端、Codex CLI 和 VS Code Codex 插件通常共用同一套配置文件，配置目录是用户目录下的 .codex 文件夹。

需要特别注意的是：如果你同时在 Windows 原生环境和 WSL 中使用 Codex，尤其是在 VS Code 中混用 Windows / WSL 环境时，需要分别配置两套 .codex 配置文件。

• Windows 原生环境：C:\Users\你的用户名\.codex
• Linux / macOS / WSL 环境：~/.codex

这类 Agent 工具在 Linux / macOS 的 Shell 环境中体验通常更好。如果你在 Windows 原生环境中使用 Codex，建议先升级到 PowerShell 7，这样可以获得更好的命令行兼容性和使用体验。

推荐环境如下：

Windows 11 + Windows Terminal + PowerShell 7 + Git + Node.js + Codex

0. Windows 环境准备

0.1 检查并安装 PowerShell 7

打开 Windows Terminal。 可以通过以下方式打开：

右键点击任务栏的 Windows 图标，然后选择「终端」或「Windows Terminal」。

在 PowerShell 中输入：

$PSVersionTable.PSVersion

如果结果中的 Major 是 7，说明已经是 PowerShell 7，例如：

Major  Minor  Patch  PreReleaseLabel BuildLabel
-----  -----  -----  --------------- ----------
7      5      5

如果你的 Major 是 5，通常说明你还在使用 Windows 自带的 Windows PowerShell 5.1，建议安装 PowerShell 7。

可以执行：

winget install --id Microsoft.PowerShell --source winget

如果已经安装过 PowerShell 7，只是版本较旧，可以执行：

winget upgrade --id Microsoft.PowerShell --source winget

如果中途提示是否同意协议，输入：

Y

然后按回车。

安装完成后，关闭终端并重新打开，再次检查版本：

$PSVersionTable.PSVersion

如果 Major 已经变成 7，说明 PowerShell 7 安装成功。

0.2 配置 Git

在 PowerShell 里输入：

git --version

如果能看到类似下面的结果，说明 Git 已经安装：

git version 2.46.0.windows.1

如果提示找不到 git 命令，可以前往下面的页面下载安装：

Git - Install for Windows

安装时建议勾选将 Git 添加到环境变量。安装完成后，重新打开终端，再次执行：

git --version

确认 Git 是否安装成功。

配置 Git 的好处是：Codex 可以帮你把当前工作区初始化为 Git 仓库。这样在修改代码时，如果出现问题，可以更方便地回退，也更适合进行版本管理。

1. 安装 Codex 客户端

Codex 目前常见的使用方式有三种：

1. Codex 桌面端
2. VS Code Codex 插件
3. Codex CLI

你可以根据自己的使用习惯选择其中一种，也可以同时安装。

1.1 安装 Codex 桌面端

Codex 桌面端最适合大多数普通用户使用，界面更直观，也不需要频繁操作命令行。

Windows 用户

Windows 用户可以通过下面的链接下载：

Codex - Windows 官方下载

这个链接会调用 Microsoft Store 安装完整安装包，下载过程可能会比较慢。

macOS 用户

macOS 用户可以在下面的页面下载：

App – Codex | OpenAI Developers

1.2 安装 VS Code Codex 插件

打开 VS Code，在左侧栏点击「扩展」，搜索：

codex

找到 Codex 插件后安装即可。

安装完成后，Codex 通常会出现在 VS Code 的侧边栏中。

1.3 安装 Codex CLI

Windows 用户

打开 Windows Terminal，并确保当前使用的是 PowerShell 7。

国内用户通常需要先配置代理。以 Clash Verge 为例，可以在设置中复制环境变量。

如果你使用的是其他代理软件，或者找不到复制环境变量的位置，也可以在开启系统代理后，到系统设置中查看代理端口号。

常见端口一般是7890。

然后在 PowerShell 中输入：

$env:all_proxy = "http://127.0.0.1:7890"

set $env:all_proxy=http://127.0.0.1:7890

Set-Variable: Cannot bind argument to parameter 'Name' because it is null.

$env:all_proxy = "http://127.0.0.1:7890"

配置代理后，执行下面的命令安装 Codex CLI：

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

如果终端出现类似下面的内容，说明安装完成：

Linux / WSL / macOS 用户

在 WSL2、Linux 原生系统或 macOS 中，打开终端，输入：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

如果你所在的网络环境无法直接访问，需要先配置代理：

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export all_proxy=http://127.0.0.1:7890

然后再执行安装命令：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

2. 配置 Codex 使用 API

如果你使用的是自定义 API 服务，例如我的网站：

https://sub.telyra.top/

或者其他兼容 OpenAI Responses API 的服务，就需要修改 Codex 的配置文件。

Codex 桌面端、VS Code 插件和 CLI 的配置文件通常位于用户目录下的 .codex 文件夹中。

2.1 Windows 配置方式

如果你是 Windows 用户，并且安装了 VS Code，可以在 PowerShell 中输入：

code $env:USERPROFILE\.codex\config.toml

在 config.toml 中写入以下内容：

model_provider = "OpenAI"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
personality = "pragmatic"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://sub.telyra.top/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true

[features]
goals = true

[features.multi_agent_v2]
enabled = true
hide_spawn_agent_metadata = true
tool_namespace = "agents"
max_concurrent_threads_per_session = 7
min_wait_timeout_ms = 10000
default_wait_timeout_ms = 30000
max_wait_timeout_ms = 120000$env:USERPROFILE.codex\config.toml

其中：

base_url = "https://sub.telyra.top/v1"

需要替换成你自己的 API 地址。

model = "gpt-5.5"
review_model = "gpt-5.5"

需要替换成你的 API 服务商支持的模型名称。

接着打开密钥文件：

code $env:USERPROFILE\.codex\auth.json

写入以下内容：

{
  "OPENAI_API_KEY": "你的密钥"
}$env:USERPROFILE.codex\auth.json

把 "你的密钥" 替换成你自己的 API Key。

如果没有 VS Code 怎么办？

如果没有安装 VS Code，或者无法使用 code 命令，可以改用 Windows 自带的记事本。

notepad $env:USERPROFILE\.codex\config.toml

notepad $env:USERPROFILE\.codex\auth.json

也可以手动进入用户目录，创建 .codex 文件夹，然后在里面创建这两个文件：

config.toml
auth.json

2.2 Linux / macOS / WSL 配置方式

Linux、macOS 和 WSL 的配置方式基本相同，只是用户目录的表示方式不同。

配置文件路径为：

~/.codex/config.toml

密钥文件路径为：

~/.codex/auth.json

可以执行：

mkdir -p ~/.codex
nano ~/.codex/config.toml

写入：

model_provider = "OpenAI"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
personality = "pragmatic"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://sub.telyra.top/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true

[features]
goals = true

[features.multi_agent_v2]
enabled = true
hide_spawn_agent_metadata = true
tool_namespace = "agents"
max_concurrent_threads_per_session = 7
min_wait_timeout_ms = 10000
default_wait_timeout_ms = 30000
max_wait_timeout_ms = 120000~/.codex/config.toml

然后创建密钥文件：

nano ~/.codex/auth.json

写入：

{
  "OPENAI_API_KEY": "你的密钥"
}~/.codex/auth.json

保存后退出。

3. 重启 Codex

配置完成后，需要重启 Codex。

如果你使用的是 Codex 桌面端，建议右键退出后重新打开。

如果你使用的是 VS Code 插件，可以重启 VS Code，或者重新加载窗口。

如果你使用的是 Codex CLI，可以关闭当前终端，重新打开后再运行 Codex。

4. 常见注意事项

4.1 第一次打开 Codex 桌面端时建议开启代理

第一次打开 Codex 桌面端时，建议先开启代理。这样 Codex 才能正常连接 OpenAI 相关网络资源，加载界面资源和中文内容。

4.2 Windows 和 WSL 要分开配置

Windows 原生环境的配置路径是：

$env:USERPROFILE\.codex

实际路径通常类似：

C:\Users\你的用户名\.codex

WSL / Linux 环境的配置路径是：

~/.codex

实际路径通常类似：

/home/你的用户名/.codex

这两个目录不是同一个目录。

如果你在 Windows 里配置好了 Codex，但进入 WSL 后发现 Codex 还是不能用，大概率就是因为 WSL 里还没有配置 ~/.codex/config.toml 和 ~/.codex/auth.json。

4.3 不要泄露 API Key

auth.json 里保存的是你的 API Key。

不要把它发给别人，也不要提交到 GitHub。

建议你在项目的 .gitignore 中加入：

.codex/
auth.json

配置完成后，重启 Codex，就可以通过自定义 API 正常使用了。

相关教程：

• Codex使用中转站时配置图像生成教程
• FastCtx：Codex Windows增强工具