# Codex CLI 配置指南

> 通过 ~/.codex/config.toml 自定义模型供应商，将 Codex CLI 接入 LLMoxy 网关，使用 Grok 4.7 等模型在终端编程。

> **📌 关于 Codex CLI**
> Codex CLI 是 OpenAI 官方的终端编码代理，用 Rust 编写，可在本地读取、修改并运行代码（[开源地址](https://github.com/openai/codex)）。它默认连接 OpenAI，但支持自定义 `model_provider`，因此可以无缝接入 LLMoxy 网关，使用 Grok 4.7 等模型。

## 安装步骤

### 1. 安装 Node.js

访问 [Node.js 官网](https://nodejs.org/)，建议下载左侧的 LTS 版本，它是长期支持版，更加稳定。

### 2. 安装 Codex CLI

打开命令行，通过 npm 全局安装：

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

macOS 用户也可以使用 Homebrew：

```bash
brew install codex
```

验证安装：

```bash
codex --version
```

Codex CLI 支持 macOS、Linux 和 Windows。Windows 建议在 PowerShell 中原生运行，或使用 WSL2 获得 Linux 原生环境。

## 配置步骤

Codex CLI 的配置文件位于 `~/.codex/config.toml`（Windows 为 `%USERPROFILE%\.codex\config.toml`）。接入 LLMoxy 只需两步：**注册一个自定义供应商** + **提供 API Key**。

### 1. 获取 API Key

进入 [LLMoxy 控制台](https://llmoxy.com/) → API Key 管理 → 复制秘钥。

> 注意：请使用 **auto** 分组的令牌。

### 2. 写入 config.toml

在 `~/.codex/config.toml` 中添加以下内容（若文件不存在则新建）：

```toml
# 默认使用 LLMoxy 供应商与模型
model = "grok-4.7"
model_provider = "llmoxy"

[model_providers.llmoxy]
name = "LLMoxy"
base_url = "https://llmoxy.com/v1"
wire_api = "responses"
env_key = "LLMOXY_API_KEY"
```

**配置项说明：**

- `model` — 默认模型名，填 LLMoxy 支持的模型（如 `grok-4.7`）
- `model_provider` — 指向下方定义的供应商 ID
- `base_url` — LLMoxy 网关地址，**带** `/v1`
- `wire_api` — 接口协议，填 `responses`，走 `/v1/responses`。Codex 只支持这一种，填 `chat` 会直接报错
- `env_key` — 存放 API Key 的环境变量名，下一步会设置

> **TIP**
> 与 Claude Code 不同，Codex CLI 的 `base_url` **必须带** `/v1`。

### 3. 设置 API Key 环境变量

`env_key` 指定的环境变量需要在系统中设置真实的 Key。

**Windows（PowerShell，永久生效）：**

```powershell
[Environment]::SetEnvironmentVariable("LLMOXY_API_KEY","你的LLMoxy API Key","User")
```

设置后 **关闭 PowerShell，重新打开一个新窗口** 才能加载。

**macOS / Linux：**

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="你的LLMoxy API Key"'
} >> ~/.zshrc   # Bash 用户改为 ~/.bashrc
source ~/.zshrc
```

验证：

```bash
echo "$LLMOXY_API_KEY"
```

你 **必须** 将 `你的LLMoxy API Key` 替换为从 [LLMoxy 控制台](https://llmoxy.com/) 复制的真实 Key。

### 4. 启动

进入你的项目目录，启动交互式会话：

```bash
codex
```

如果能正常对话并执行任务，说明已成功接入 LLMoxy。

## 常用操作

### 切换模型与推理强度

会话中输入 `/model` 即可切换模型，或调整推理强度（reasoning effort）。也可以在启动时通过 `-m` 指定：

```bash
codex -m grok-4.7
```

### 审批模式（Approval modes）

Codex 在编辑文件或执行命令前会请求确认。可在会话中用 `/approvals` 切换，或启动时指定：

```bash
codex --ask-for-approval      # 每步确认（默认，最稳妥）
codex --full-auto             # 自动执行，仅在工作目录内、网络受限的沙箱中运行
```

> **💡 提示**
> 首次在某个项目目录运行时，Codex 会询问是否信任该目录。

### 脚本化运行（非交互）

用 `exec` 子命令把一次性任务交给 Codex，适合在脚本或 CI 中调用：

```bash
codex exec "为 main.go 中的 ParseConfig 补充单元测试"
```

### 图像输入

可附带截图或设计稿，让 Codex 结合图片理解需求：

```bash
codex -i screenshot.png "按这张设计稿实现登录页"
```

### 联网搜索

启用 Web 搜索获取最新信息：

```bash
codex --search
```

### 接入 MCP 工具

在 `config.toml` 中通过 `[mcp_servers.*]` 注册 MCP 服务，为 Codex 提供第三方工具与上下文。该配置与 LLMoxy 供应商配置可以共存：

```toml
[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]
```

## 常见问题

### `npm install -g` 提示权限错误

不要使用 `sudo npm install -g`。推荐用 nvm 管理 Node.js，或修改 npm 全局目录：

```bash
npm config set prefix ~/.npm-global
```

然后将 `~/.npm-global/bin` 加入 PATH。macOS 用户也可通过 Homebrew 安装 Node.js（无需 sudo）。

### 启动后仍要求登录 OpenAI 账号

确认 `config.toml` 中 `model_provider = "llmoxy"` 已生效，且 `LLMOXY_API_KEY` 环境变量已设置。配置了自定义供应商后 Codex 使用 API Key 鉴权，无需 ChatGPT 登录。

### 报错 404 / 模型不存在

- 确认 `base_url` 带 `/v1`：`https://llmoxy.com/v1`
- 确认 `model` 填写的是 LLMoxy 支持的模型名
- 确认 `wire_api = "responses"`：Codex 已不支持 `chat`，旧教程里的 `wire_api = "chat"` 会直接报错

### 环境变量未生效

- Windows：`SetEnvironmentVariable(...,"User")` 需 **重新打开终端**
- macOS / Linux：执行 `source ~/.zshrc`（或 `~/.bashrc`），或重开终端，再用 `echo "$LLMOXY_API_KEY"` 验证

### API 调用失败 / 余额问题

- 检查 API Key 没有多余空格
- 到 [LLMoxy 控制台](https://llmoxy.com/) 检查账户余额与令牌分组（建议用 **auto** 分组）

### 远程服务器连接超时（Linux）

- 检查网络：`curl -I https://llmoxy.com`
- 如需代理，配置 `HTTPS_PROXY` 环境变量

本文是 https://llmoxy.com/docs/code-tutorials/codex-cli 的 markdown 版本。
