# Codex CLI 安装与接入 4SToken

本文档仅适用于 Codex CLI。Codex Desktop 是单独的桌面客户端，请查看 `/tools/codex-desktop`，不需要安装 Node.js 或 `npm install -g @openai/codex`。

Codex CLI 默认通过 `POST /v1/responses` 调用模型；chat-only 上游使用脚本生成的 `chat` profile，通过 `POST /v1/chat/completions` 调用网关。

Codex 下拉能显示哪些模型，取决于脚本写入的 `~/.codex/signal-model-catalog.json`。CLI 脚本会写入实际 modelCode，能同名则同名，不做旧别名改写。


## 安装前准备

1. 已创建 Portal Client Key，格式为 `sk-...`。
2. 已安装 Node.js LTS 与 npm。
3. 已执行 `npm install -g @openai/codex`（若尚未安装，见 [OpenAI Codex 文档](https://developers.openai.com/codex)）。
4. 确认网关 Base URL：`https://api.4stoken.cn/api`。
5. 确认要使用的 Codex 模型名，例如 `gpt-5.5`、`gpt-5.3-codex`、`claude-opus-4-8`、`openrouter-free`。

## Windows 安装与配置

1. 安装 Node.js LTS：

```powershell
winget install OpenJS.NodeJS.LTS
```

也可以从 `https://nodejs.org/` 下载 LTS 安装包。

2. 关闭并重新打开 PowerShell，确认 Node.js 与 npm 可用：

```powershell
node -v
npm -v
```

3. 安装 Codex CLI：

```powershell
npm.cmd uninstall -g codex
npm.cmd install -g @openai/codex
codex --version
```

Windows PowerShell 如果提示无法加载 `npm.ps1`，请使用 `npm.cmd`；如果曾经安装过 `codex` 旧包，必须先卸载，否则会出现 `lineno` / `filename` circular dependency 警告。

4. 执行配置脚本：

```powershell
$f = Join-Path $env:TEMP 'codex.ps1'
Invoke-WebRequest -Uri '{PORTAL}/docs/scripts/codex.ps1' -OutFile $f -UseBasicParsing
powershell -NoProfile -ExecutionPolicy Bypass -File $f -ApiKey sk-你的Key
```

脚本会写入：

```text
%USERPROFILE%\.codex\config.toml
```

如果手动编辑 `config.toml`，Windows 路径不要直接写成双引号里的 `C:\...`，要用单引号或把反斜杠转义。

## macOS / Linux 安装与配置

1. 安装 Node.js LTS。

macOS：

```bash
brew install node
```

Ubuntu / Debian 可使用 NodeSource LTS 或发行版包管理器安装：

```bash
sudo apt update
sudo apt install -y nodejs npm
```

2. 确认 Node.js 与 npm 可用：

```bash
node -v
npm -v
```

3. 安装 Codex CLI：

```bash
npm uninstall -g codex
npm install -g @openai/codex
codex --version
```

4. 执行配置脚本：

```bash
curl -fsSL '{PORTAL}/docs/scripts/codex.sh' \
  | GATEWAY_BASE_URL='https://api.4stoken.cn/api' bash -s -- sk-你的Key
```

chat-only 上游可使用：

```bash
GATEWAY_CODEX_CHAT_MODEL=openrouter-free \
curl -fsSL '{PORTAL}/docs/scripts/codex.sh' \
  | GATEWAY_BASE_URL='https://api.4stoken.cn/api' bash -s -- sk-你的Key
```

## 核心配置

- `model_provider = "signal"`
- `base_url = https://api.4stoken.cn/api/v1`
- 默认 `wire_api = "responses"`
- `~/.codex/chat.config.toml` 固定 `wire_api = "chat"`，用于仅支持 `chat.completions` 的上游
- 默认 model：`gpt-5.5`
- `GATEWAY_CODEX_EXTRA_MODELS=model-a,model-b` 可追加写入 Codex 模型目录

## Codex 模型映射

| Codex 里选择 | 系统实际 modelCode |
| --- | --- |
| `gpt-5.5` | `gpt-5.5` |
| `gpt-5.4` | `gpt-5.4` |
| `gpt-5.4-mini` | `gpt-5.4-mini` |
| `gpt-5.4-nano` | `gpt-5.4-nano` |
| `gpt-5.3-codex` | `gpt-5.3-codex` |
| `claude-opus-4-8` | `claude-opus-4-8` |
| `claude-opus-4-6` | `claude-opus-4-6` |

完整可用范围以 `GET /v1/models` 返回为准。

## 配置检查

### Codex CLI

```bash
codex --version
curl -sS 'https://api.4stoken.cn/api/v1/models' -H 'Authorization: Bearer sk-你的Key'
codex --profile openrouter-free
```

如果使用 chat-only profile：

```bash
codex --profile chat
```

## 常见问题

### 找不到 codex 命令

请先确认 Node.js 与 npm 可用，然后重新安装 Codex CLI：

```bash
node -v
npm -v
npm uninstall -g codex
npm install -g @openai/codex
codex --version
```

Windows 用户如果仍然找不到 `codex`，请关闭并重新打开 PowerShell，再检查 npm 全局安装目录是否加入 `Path`。

### 返回模型路由错误

Codex 默认 profile 走 `responses` 协议，请确认该模型在 Gateway 已配置可用路由。仅支持 `chat.completions` 的模型请使用 `codex --profile chat` 或把主配置临时设为 `GATEWAY_CODEX_WIRE_API=chat` 后重跑脚本。

详情见 Portal：`/tools/codex`