# Codex VS Code Extension: Install and Configure Passion8

> Install OpenAI’s official Codex VS Code extension and configure Passion8 API-key access through user-level auth.json and config.toml for local projects.

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

The official Codex extension brings conversations, project context, and change review into your editor sidebar. Passion8 setup requires only a **Passion8 URL, API key, and Responses-compatible model ID**. The extension and CLI share user-level configuration; you do not need to install the CLI before using the extension.

## 1. Install the Official Extension

Search for **Codex** in VS Code's Extensions view. Verify the publisher **OpenAI** and extension ID `openai.chatgpt`, or open the [official listing](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt). Compatible editors such as Cursor and Windsurf can also use this extension.

If the `code` command is available, install from a terminal:

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

Open your project folder and select the Codex icon in the Activity Bar. If the icon is missing, run **Codex: Open Codex Sidebar** from the Command Palette.

JetBrains and Xcode have separate official integrations rather than this VS Code extension. This page's controls and settings apply to VS Code-compatible editors.

## 2. Configure Passion8

Choose [CC-Switch setup](https://docs.passion8.cc/en/docs/codex/config#configure-with-cc-switch-recommended) or the manual method below. Both should result in the same provider, URL, and authentication.

### Manual Configuration Paths

| System | User configuration directory |
| --- | --- |
| macOS / Linux | `~/.codex/` |
| Windows | `%USERPROFILE%\.codex\` |
| WSL / Remote SSH / Dev Container | The user's home directory in the environment running the extension |

Select the gear in the Codex sidebar, then **Codex Settings → Open config.toml** to confirm the active file. Back up existing configuration and merge the fields below; do not overwrite existing MCP, project permissions, or other providers.

```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` is an example ID with a recorded Passion8 deployment. Replace `model` with the exact **Responses** model enabled for your token in the dashboard. For long conversations, see context and automatic compaction settings in the [complete configuration guide](https://docs.passion8.cc/en/docs/codex/config).




`requires_openai_auth = true` selects Codex's API-key authentication storage; it does not require registering an OpenAI account. The key saved below is a Passion8 key, and model requests go to `base_url`.




### Save the API Key

Write the following to `auth.json` in the same directory:

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

If the extension still shows its authentication screen, you can choose **Use API Key** and enter your Passion8 key. `forced_login_method = "api"` enforces the API-key path; file storage lets the extension and CLI read the same credentials.

Keep the real key in the user-level credential file and do not commit it to a project. Do not define the gateway provider in a project's `.codex/config.toml`: current Codex restricts provider and authentication configuration to user-level and other trusted configuration layers.

### If CC-Switch Is Already Configured

Enable Passion8 on CC-Switch's GPT / Codex page and check the user-level files above. Use the extension's **Open config.toml** command to confirm it reads files in the same environment. Changes made by CC-Switch on macOS are not automatically copied into another Remote SSH host or a WSL user directory.

## 3. Reload and Start a New Session

Save the files, run **Developer: Reload Window**, reopen Codex, and create a new local session. Check that the model picker or Codex Settings matches the configured ID.

First send a request that requires no tools:

```text
Reply with one sentence saying "Connected successfully". Do not read files, edit files, or run commands.
```

After the response, check the matching request time, model, and usage in the Passion8 dashboard to confirm the route. If the CLI is also installed, `codex login status` can check the authentication method, but the CLI is not required to connect the extension.

## 4. Make a Small Project Change

Open a file and provide selected code or the file as context. Ask Codex to read and explain it first, then make a clearly scoped change:

```text
Read the current file and identify one edge-case issue. Explain your plan first, edit only this file, run existing relevant tests, and summarize the diff.
```

Check file writes and command requests before approving them. Review the diff and relevant test results in the editor. Agent settings such as models, reasoning effort, permissions, and MCP are controlled by `config.toml`. The editor's `chatgpt.*` settings mainly control panel behavior; they are not where you enter the gateway URL.

## Local Capabilities and Cloud Entry Points

| Capability | This setup path |
| --- | --- |
| Read files, selections, and project context | Available locally, subject to project permissions |
| Edit files, run local commands, and review diffs | Available locally, subject to approvals and sandbox settings |
| Use MCP | Supported through user configuration; tools may require their own authentication |
| Switch models and reasoning effort | Requires support from the model, client, and Passion8 route |
| Codex Cloud / Run in the cloud | Outside this API-key setup; local gateway settings do not replace cloud account permissions |

## Extension Choice and Account FAQ

### Does the official Codex extension require a ChatGPT subscription?

Local Passion8 API-key access does not require a ChatGPT subscription or OpenAI OAuth. Configure the URL, key, and Responses-compatible model shown here. Local gateway configuration does not automatically enable cloud task entry points.

### Should I use Codex to switch Claude, Gemini, and Grok models?

Do not assume every vendor’s model works in Codex; first verify the Responses protocol required by the client. To use four vendors’ Chat Completions models in one editor panel, follow [Cline multi-model configuration](https://docs.passion8.cc/en/docs/cline).

## Troubleshooting

| Symptom | Check first |
| --- | --- |
| Extension still asks for credentials | Correct environment for `auth.json`, saved `OPENAI_API_KEY`, and a reloaded window |
| `401` | Complete active key, actual Passion8 Base URL, and stale credential storage |
| `404` or model missing | Exact model ID and `/v1`; an incorrectly appended `/v1/responses`; Responses support for the ID |
| Cline works but Codex does not | Cline's compatible path uses Chat Completions; current Codex supports only Responses, so check protocol access |
| Old model remains after editing config | Reload and create a new session; check trusted project model overrides and active configuration sources |
| Local works but WSL / SSH fails | Configure credentials, user directory, and gateway connectivity in the environment running the extension |
| Cloud entry point cannot proceed | Return to local work; cloud services are separate from the local agent capabilities provided by this key |

## Next Steps



- [Complete Codex Configuration](https://docs.passion8.cc/en/docs/codex/config): CC-Switch, manual setup, context windows, and automatic compaction.
- [Permissions and Sandboxing](https://docs.passion8.cc/en/docs/codex/permissions-sandboxing): Choose local permissions and approval behavior.
- [Cline Multi-model Setup](https://docs.passion8.cc/en/docs/cline): Configure different vendors



## Official References

- [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)