# ChatGPT / Codex 配置

Codex 是 OpenAI 官方的命令行 AI 编程助手。通过 4AICode API 接入后，可以在控制台管理密钥、团队额度和用量，按实际 token 用量计费。

> 💡 **新手建议**：推荐优先使用 **【方式一：连接助手（图形界面）】**，无需敲命令，点几下鼠标就能搞定。

---

## 准备工作：获取你的 Token

无论使用哪种方式，都需要先拿到属于你的 4AICode 访问令牌（Token）：

1. 登录 4AICode，进入 [仪表盘 → 管理 Tokens](https://4aicode.net/tokens)。
2. 点击 **「新建 Token」**。
3. 复制生成的字符串（格式为 `sk-4ai-<your-token>`）。

> ⚠️ **注意**：
> - Token 只会完整显示一次，请先妥善保存到记事本或密码管理器。
> - 本文示例中的 `sk-4ai-<your-token>` 是占位符，请务必替换为您自己的真实 Token。
> - 使用命令行时，请将尖括号及其中的占位内容整体替换为真实 Token。
> - Token 等同于密码，请勿泄露给他人或上传到 GitHub。

---

## 方式一：使用连接助手（推荐小白使用）

4AICode 连接助手使用 MyGo 构建原生桌面界面，无需使用终端敲命令。

### 1. 下载连接助手客户端

| 系统平台 | 下载地址 | 说明 |
| --- | --- | --- |
| **Windows 10 / 11** (64位) | [📥 下载连接助手 Windows 版 (.exe)](/downloads/windows/4aicode-assistant-windows-amd64.exe) | 下载后直接双击运行 |
| **macOS 12+** (Apple Silicon / M系列芯片) | [📥 下载连接助手 Apple Silicon 版 (.dmg)](/downloads/macos/4aicode-assistant-macos-arm64.dmg) | 打开 DMG，拖入「应用程序」 |
| **macOS 12+** (Intel 芯片) | [📥 下载连接助手 Intel 版 (.dmg)](/downloads/macos/4aicode-assistant-macos-amd64.dmg) | 打开 DMG，拖入「应用程序」 |

> Windows 包当前尚未完成发布者签名，首次运行可能显示 SmartScreen 安全提示。Defender 检测结果仍待验证。请在下载目录执行 `certutil -hashfile 4aicode-assistant-windows-amd64.exe SHA256`（Windows），并与 [SHA256SUMS.txt](/downloads/SHA256SUMS.txt) 中对应文件行开头的哈希值对比。

macOS 的 Apple Silicon 和 Intel 发布包均完成 Developer ID 签名及 Apple 公证。打开 DMG 后拖入「应用程序」即可安装。

*(安全校验参考：[SHA-256 校验文件](/downloads/SHA256SUMS.txt) · [版本信息](/downloads/latest.json))*

下载链接下方会显示版本。更新前请从助手的系统托盘或菜单栏选择 **「退出」**；关闭窗口会保留后台进程。替换并重新打开程序后，对比窗口右上角的版本号、构建编号与下载页是否一致。

### 2. 软件内 3 步完成配置

1. **连接账号**：打开助手，粘贴你准备好的 `sk-4ai-<your-token>`，根据所在网络选择 **「国内线路」** 或 **「国际线路」**。助手自动加载该线路的模型列表，从 **模型下拉框** 选择后点击 **「连接」**；修改 Token 或线路会重新加载，也可点击 **「刷新模型」**。
2. **一键安装并启动**：点击 **「选择项目并启动 Codex」**，首次使用且本机缺少 Codex CLI 时，助手会先下载安装，再在指定文件夹中启动；下载期间请等待界面提示。
3. **后台运行**：关闭窗口后，助手继续驻留在系统托盘（Windows）或顶部菜单栏（macOS），可随时重新打开。

> Token 会安全保存在系统凭据管理器中。输入框右侧的眼睛图标可显示或隐藏当前输入，方便核对；点击连接时恢复隐藏。

### 3. 接入 Windows 官方桌面应用

本地 Codex 功能支持通过 API 密钥登录，可以直接使用 4AICode 额度。首次接入按以下步骤操作：

1. 在连接助手里选择模型并连接；模型列表支持鼠标滚轮和键盘选择。
2. 点击 **「复制桌面登录密钥」**，助手会准备桌面登录配置并复制本机连接密钥。
3. **彻底退出并重新打开**官方 ChatGPT / Codex 桌面应用，选择 **「其他登录方式 → API 密钥」**，在 **「OpenAI API 密钥」** 输入框粘贴，点击 **「继续」**。
4. 保持助手运行，在桌面应用中新建本地任务开始使用。模型或线路改变后，重新启动桌面应用。

桌面应用与助手需使用同一 Windows 用户及同一个 Codex 配置目录；默认是 `%USERPROFILE%\.codex`。设置了 `CODEX_HOME` 时，两者需指向同一目录。

`config.toml` 含本机连接密钥，应按私密文件保管；分享排障信息前清理密钥。「恢复原配置」会退出助手的桌面登录模式。

复制的密钥只用于连接本机助手，4AICode Token 保存在系统凭据库。已有 ChatGPT 登录用户可以保留当前登录，点击该按钮后重启应用。API 密钥模式支持本地 Codex 工作；ChatGPT 网页聊天、工作区和云端功能各自使用其官方账号权限。[官方认证说明](https://learn.chatgpt.com/docs/auth#sign-in-with-an-api-key)

### 桌面应用提示「Model provider `fouraicode_assistant` not found」

这表示桌面应用加载的配置缺少助手供应商定义。按以下步骤恢复：

1. 从系统托盘退出旧版助手，下载最新版并点击 **「连接」**。界面仍显示已连接时，先点 **「断开」** 再连接。v0.1.2 起，助手会定期检查配置；备份可确认配置归属时，重连可补回缺失的定义。
2. **彻底退出并重新打开**官方 ChatGPT / Codex 桌面应用，再打开出错的会话。
3. 仍报错时，检查两个应用是否使用同一 Windows 用户及配置目录；设置了 `CODEX_HOME` 时，两者需保持一致。联系支持时提供助手版本、操作步骤及配置目录即可。

使用过 **「恢复原配置」** 的用户，继续助手旧会话前需重新连接。要使用原供应商，请重启桌面应用并新建任务。

### 助手提示连接设置发生变化

点击 **「重新配置并连接」**，在弹窗中选择 **「备份并连接」**，即可切回 4AICode。助手会先保存当前设置和旧备份，保留项目授权、MCP 与其他供应商；之后点击「恢复原配置」会回到此次切换前的设置。完成后重启桌面应用。

### 助手连接失败

按提示区分处理：响应超时可重试；代理错误请检查本机代理软件与端口；证书错误请检查电脑日期时间；模型列表异常请点击「刷新模型」，持续出现时联系支持检查服务。Token、额度与限额错误按提示前往仪表盘处理。联系支持时提供助手版本与错误提示；分享配置文件前清理密钥。

---

## 方式二：命令行快速接入（适合开发者）

如果你习惯使用终端命令行，只需执行安装与一键配置脚本，耗时约 2 分钟。


**macOS / Linux**


### 1. 打开终端
按快捷键 `⌘ + 空格`，输入「终端」并按回车。

### 2. 安装 Codex CLI
确保电脑已安装 Node.js 或 Homebrew，在终端运行以下任一命令：

```bash
# 方式 A：通过 npm 安装（推荐，需要 Node.js 16+）
npm install -g @openai/codex

# 方式 B：通过 Homebrew 安装（仅 macOS）
brew install --cask codex
```

运行 `codex --version`，如果输出版本号即表示安装成功。

### 3. 执行一键配置脚本
将命令中的 `sk-4ai-<your-token>` 替换为你自己的 Token 后运行：

```bash
# 中国大陆直连线路（默认）
curl -fsSL https://4aicode.net/codex-setup.sh | bash -s install 'sk-4ai-<your-token>'

# 国际网络（使用 .com 线路）
export RELAY4AI_BASE_URL=https://relay.4aicode.com/v1
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s install 'sk-4ai-<your-token>'
```

看到终端输出 `✓ 已写入 ...` 即表示配置完成！

### 4. 验证运行
**新开一个终端窗口**，进入你的代码目录后输入：

```bash
codex
```
试着输入一句：`解释一下当前目录的文件结构`。若正常回答，说明已接通 4AICode。


**Windows**


### 1. 打开 PowerShell
按 `Win 键`，搜索并打开 **PowerShell**。

### 2. 安装 Codex CLI
确保已安装 Node.js，在 PowerShell 中运行：

```powershell
npm install -g @openai/codex
```

运行 `codex --version`，如果输出版本号即表示安装成功。

### 3. 执行一键配置脚本
在 PowerShell 中运行一键配置脚本：

```powershell
# 交互式配置（会提示粘贴 Token 并选择模型）
irm https://4aicode.net/codex-setup.ps1 | iex
```

如果不想等待交互提示，也可以直接传入 Token（记得替换占位符）：

```powershell
& ([scriptblock]::Create((irm https://4aicode.net/codex-setup.ps1))) install 'sk-4ai-<your-token>'
```

*如果身处海外/使用国际网络，在运行前先执行：`$env:RELAY4AI_BASE_URL='https://relay.4aicode.com/v1'`*

### 4. 验证运行
**新开一个 PowerShell 窗口**，进入代码目录并运行：

```powershell
codex
```
向 Codex 发送测试消息，如果能正常交互即可开始使用！


---

## 常用操作指南

### 1. 切换 AI 模型与推理强度

使用连接助手时，点击 **「断开」**，从模型下拉框选择其他模型，再点击 **「连接」**并重新启动 Codex。

使用命令行接入时，可以修改本地配置文件：

- **macOS / Linux** 路径：`~/.codex/config.toml`
- **Windows** 路径：`%USERPROFILE%\.codex\config.toml`

打开文件后，修改以下两项即可（其余保持不变）：

```toml
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"
```

| 模型名称 | 适用场景与特点 |
| --- | --- |
| `gpt-5.6-terra` | **日常编码推荐（默认）**：速度与效果平衡最好 |
| `gpt-6-astra` | **新一代旗舰**：综合实力极强，按官方价 1.5 折计费 |
| `gpt-5.6-sol` | **复杂工程最强推理**：适合攻坚架构难题（支持 `max` 推理强度） |
| `gpt-5.6-luna` | **快速经济型**：轻量任务，省额度 |
| `gpt-5.5` / `gpt-5.4` | 兼容老工作流 |

*注：推理强度可选 `low`、`medium`、`high`、`xhigh`；修改保存后，重新启动 Codex 即可生效。*

### 2. 查看当前状态与一键卸载还原


**macOS / Linux**


```bash
# 查看当前配置的 provider 与模型
curl -fsSL https://4aicode.net/codex-setup.sh | bash -s status

# 卸载并恢复为安装前的原始配置
curl -fsSL https://4aicode.net/codex-setup.sh | bash -s uninstall
```


**Windows**


```powershell
# 查看状态
& ([scriptblock]::Create((irm https://4aicode.net/codex-setup.ps1))) status

# 卸载并恢复原始配置
& ([scriptblock]::Create((irm https://4aicode.net/codex-setup.ps1))) uninstall
```


---

## 常见问题与排错（FAQ）

### Q1：提示 `codex: command not found` 或不是内部命令？
- **原因**：尚未安装 Codex CLI，或全局路径没有刷新。
- **解决**：请先关闭当前命令行，新开一个窗口重试；若依然提示，检查 Node.js 是否安装正确，并重新执行安装命令 `npm install -g @openai/codex`。

### Q2：运行 Codex 时报错 `401 Unauthorized`？
- **原因**：Token 不正确或已被撤销。
- **解决**：检查命令里的 `sk-4ai-<your-token>` 是否忘了替换为自己的真实 Token，或去 [仪表盘](https://4aicode.net/tokens) 重新生成一个 Token 并重跑配置脚本。

### Q3：Windows PowerShell 提示「脚本被系统执行策略拦截」？
- **解决**：使用上文推荐的 `& ([scriptblock]::Create(...))` 方式运行，或者在 PowerShell 中运行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` 允许本地脚本执行。

### Q4：修改了模型或配置后，为什么感觉没生效？
- **解决**：Codex 进程在启动时会缓存配置。请彻底退出正在运行的 Codex 会话，关掉终端窗口，新开一个窗口后再运行。

### Q5：如何使用 Codex 官方桌面客户端（Codex App）？
- 使用连接助手完成连接，点击 **「复制桌面登录密钥」**，彻底退出并重开桌面应用，再选择 API 密钥登录并粘贴。完整步骤见上方「接入 Windows 官方桌面应用」。
- 切回官方提供商时，先在助手中恢复原配置；使用过本机密钥登录的用户随后在桌面应用里退出该登录，再选择自己的官方登录方式。

---

## 其他工具与 SDK 接入

如果你在日常开发中使用其他编辑器、客户端或代码脚本，也可以无缝接入 4AICode 的 ChatGPT 模型池：

| 接入工具/场景 | 接入说明 |
| --- | --- |
| **CC Switch**（图形化切换器） | 参考 [CC Switch 配置指南](/docs/guides/cc-switch) |
| **VS Code / Cursor / Windsurf** | 参考 [VS Code / Cursor 指南](/docs/guides/vscode) |
| **Claude Code 调 GPT 模型** | 参考 [Claude 配置指南](/docs/guides/claude) |
| **Droid / Pi** | 参考 [Droid / Pi 接入指南](/docs/guides/droid-pi) |
| **OpenAI 官方 Python / Node SDK** | 配置 Base URL 与 API Key 即可（见下方代码） |

### 统一接口参数
- **Base URL**：`https://relay.4aicode.net/v1`（国际网络用 `https://relay.4aicode.com/v1`）
- **API Key**：你的 4AICode Token（`sk-4ai-<your-token>`）

#### Python SDK 示例
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.net/v1",
    api_key="sk-4ai-<your-token>",  # 换成你的真实 Token
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "你好，请写一段冒泡排序"}],
)

print(response.choices[0].message.content)
```

#### cURL 请求示例
```bash
curl https://relay.4aicode.net/v1/chat/completions \
  -H "Authorization: Bearer sk-4ai-<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

---

## 附录：手动高级配置（开发者备查）

> 💡 正常使用无需阅读此节。仅供需要审计配置或手动合并配置的高级开发者参考。

Codex 配置文件存放位置：
- macOS / Linux：`~/.codex/`
- Windows：`%USERPROFILE%\.codex\`

### 1. `auth.json`
保留 ChatGPT 登录凭据骨架：
```json
{
  "auth_mode": "chatgpt",
  "OPENAI_API_KEY": null,
  "tokens": {
    "id_token": "...",
    "access_token": "...",
    "refresh_token": "...",
    "account_id": "..."
  },
  "last_refresh": "..."
}
```

### 2. `config.toml`
配置自定义 4AICode 模型提供商：
```toml
model_provider = "OpenAI"
openai_base_url = "https://relay.4aicode.net/v1"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.OpenAI]
name = "4aicode"
base_url = "https://relay.4aicode.net/v1"
wire_api = "responses"
experimental_bearer_token = "sk-4ai-<your-token>"
requires_openai_auth = true
```