# Codex VS Code 扩展：安装与 Passion8 API Key 配置

> 安装 OpenAI 官方 Codex VS Code 扩展，通过用户级 auth.json 与 config.toml 配置 Passion8 API Key、地址和 Responses 模型。

URL: https://docs.passion8.cc/docs/codex/ide
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

Codex 官方扩展把对话、项目上下文和改动审阅放进编辑器侧边栏。本站接入只需要 **Passion8 地址、API Key 和支持 Responses 的模型 ID**。扩展和 CLI 共用用户级配置；不需要先安装 CLI 才能使用扩展。

## 1. 安装官方扩展

在 VS Code 扩展面板搜索 **Codex**，核对发布者 **OpenAI** 和扩展 ID `openai.chatgpt`，或打开 [官方扩展条目](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt)。Cursor、Windsurf 等兼容编辑器也可使用此扩展。

已经配置 `code` 命令时，可在终端安装：

```bash
code --install-extension openai.chatgpt
```

打开项目文件夹，点击活动栏中的 Codex 图标；找不到图标时，在命令面板执行 **Codex: Open Codex Sidebar**。

JetBrains 和 Xcode 有各自的官方集成，不是安装这个 VS Code 扩展；本文的按钮与设置步骤面向 VS Code 兼容编辑器。

## 2. 配置 Passion8

选择 [CC-Switch 配置](https://docs.passion8.cc/docs/codex/config#用-cc-switch-配置推荐) 或下面的手动方式。两种方式得到的 Provider、地址和认证应一致。

### 手动配置路径

| 系统 | 用户配置目录 |
| --- | --- |
| macOS / Linux | `~/.codex/` |
| Windows | `%USERPROFILE%\.codex\` |
| WSL / Remote SSH / Dev Container | 扩展实际运行环境里的用户主目录 |

在 Codex 侧边栏点击齿轮，选择 **Codex Settings → Open config.toml** 可以确认实际配置文件。先备份已有配置，合并下面字段；不要覆盖已有 MCP、项目权限或其他 Provider。

```toml title="~/.codex/config.toml"
model_provider = "Passion8"
model = "gpt-6-sol"
model_reasoning_effort = "medium"
forced_login_method = "api"
cli_auth_credentials_store = "file"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.Passion8]
name = "Passion8"
base_url = "https://passion8.cc/v1"
wire_api = "responses"
requires_openai_auth = true
```

`gpt-6-sol` 是本站已记录部署的示例 ID。把 `model` 换成控制台向你的令牌开放、支持 **Responses** 的精确型号。长会话的上下文和自动压缩参数见 [完整配置教程](https://docs.passion8.cc/docs/codex/config)。




`requires_openai_auth = true` 表示使用 Codex 的 API Key 认证存储，不表示要求注册 OpenAI 账号。下面保存的是 Passion8 Key，实际模型请求发往 `base_url`。




### 保存 API Key

在同一目录的 `auth.json` 写入：

```json title="~/.codex/auth.json"
{
  "OPENAI_API_KEY": "sk-your-Passion8-API-Key"
}
```

也可以在扩展仍显示认证入口时选择 **Use API Key**，填写 Passion8 Key。`forced_login_method = "api"` 固定使用 API Key 路径；文件存储方式让扩展和 CLI 读取同一份认证。

只把真实 Key 放在用户级认证文件，不要提交进项目。不要在项目 `.codex/config.toml` 中定义网关 Provider：当前 Codex 将 Provider 和认证相关配置限制在用户级等可信配置层。

### 已用 CC-Switch 配好

在 CC-Switch 的 GPT / Codex 页面启用 Passion8，然后核对上述用户级文件。打开扩展的 **Open config.toml** 确认它读取的是同一环境里的文件。CC-Switch 在 macOS 改的配置不会自动写进另一台 Remote SSH 主机或 WSL 的用户目录。

## 3. 重载扩展并新建会话

保存后执行 **Developer: Reload Window**，重新打开 Codex，新建一个本地会话。检查模型选择器或 Codex Settings 中的模型与所填 ID 一致。

先发不需要工具的请求：

```text
用一句话回复“连接成功”。不要读取文件、修改文件或执行命令。
```

返回后到 Passion8 控制台核对请求时间、模型和用量，确认实际走本站。若电脑还安装了 CLI，也可运行 `codex login status` 检查认证方式，但 CLI 不是扩展连接的必需步骤。

## 4. 在项目里完成一次小改动

打开文件，把选中代码或文件作为上下文交给 Codex。先让它阅读和解释，再进行范围明确的修改：

```text
阅读当前文件并指出一个边界条件问题。先说明修改方案，只修改这个文件，运行已有的相关测试，最后给出 diff 摘要。
```

遇到文件写入或命令审批时，核对操作后再批准。完成后在编辑器查看 diff、检查相关测试结果。模型、推理强度、权限、MCP 等代理设置由 `config.toml` 控制；`chatgpt.*` 编辑器设置主要控制面板表现，不是填写网关地址的位置。

## 本地能力与云端入口

| 功能 | 本文接入路径 |
| --- | --- |
| 读取文件、选中代码和项目上下文 | 本机扩展可用，受项目权限约束 |
| 修改文件、运行本地命令、审阅 diff | 本机扩展可用，按审批与沙箱配置执行 |
| 使用 MCP | 用户配置支持，工具自身的认证另行配置 |
| 切换模型与推理强度 | 取决于模型、客户端和 Passion8 路由的共同支持 |
| Codex Cloud / Run in the cloud | 不属于本站 API Key 接入流程；本机网关配置不能直接代替云端账号权限 |

## 扩展选择与账号问题

### 用官方 Codex 扩展需要 ChatGPT 订阅吗？

本地 Passion8 API Key 接入无需 ChatGPT 订阅或 OpenAI OAuth。使用本文的地址、Key 和支持 Responses 的模型即可配置；云端任务入口不由本地网关配置自动开通。

### 想切换 Claude、Gemini 和 Grok，也用 Codex 扩展吗？

不要把所有厂商模型都当作 Codex 模型。先确认模型支持 Codex 所需的 Responses 协议；若希望在同一个编辑器面板使用四家厂商的 Chat Completions 模型，看 [Cline 多模型配置](https://docs.passion8.cc/docs/cline)。

## 常见问题

| 现象 | 先检查 |
| --- | --- |
| 打开扩展仍要求认证 | `auth.json` 是否在正确环境；是否保存 `OPENAI_API_KEY`；是否重载窗口 |
| `401` | Key 完整且有效；实际 Base URL 是否为 Passion8；是否读取了旧认证存储 |
| `404` 或模型不存在 | 模型 ID 和 `/v1`；是否错填 `/v1/responses`；所选 ID 是否支持 Responses |
| Cline 能用，Codex 不能用 | Cline 兼容路径是 Chat Completions；Codex 当前只支持 Responses，检查协议权限 |
| 修改配置后仍用旧模型 | 重载窗口并新建会话；检查可信项目里的模型覆盖与当前配置来源 |
| 本机能用，WSL / SSH 失败 | 在扩展实际运行的系统里配置用户目录、Key 和网关网络 |
| 点击云端入口无法继续 | 返回本地工作模式；云端服务不是本站 Key 提供的本地代理能力 |

## 接着看



- [完整 Codex 配置](https://docs.passion8.cc/docs/codex/config): CC-Switch、手动配置、上下文窗口和自动压缩。
- [权限与沙箱](https://docs.passion8.cc/docs/codex/permissions-sandboxing): 选择合适的本地权限与审批方式。
- [Cline 多模型配置](https://docs.passion8.cc/docs/cline): 在同一个编辑器扩展里配置不同厂商的 Chat Completions 模型。



## 官方参考

- [Codex IDE extension](https://developers.openai.com/codex/ide)
- [IDE settings](https://developers.openai.com/codex/ide/settings)
- [Authentication](https://developers.openai.com/codex/auth)
- [Advanced configuration](https://developers.openai.com/codex/config-advanced)
- [Configuration reference](https://developers.openai.com/codex/config-reference)