---
url: https://limapi.com/docs/agents/codex.md
---
# OpenAI Codex

OpenAI Codex CLI 是 OpenAI 推出的终端编程 Agent。通过 OpenAI 兼容端点即可接入 LimAPI。

## 安装

需要 Node.js 18+：

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

验证安装：

```bash
codex --version
```

## 配置接入凭证

| 配置项 | 说明 |
| --- | --- |
| API Key | [Portal](https://limapi.com/) 创建的 LimAPI API Key（`sk-` 开头） |
| Base URL | `https://limapi.com/api/v1`（OpenAI 兼容端点） |
| 可用模型 | 平台支持的任意模型，完整列表通过 `GET /api/v1/models` 查询或在 Portal 模型广场查看 |

接入需要编辑配置文件 `~/.codex/config.toml` 并配置环境变量 `OPENAI_API_KEY`。

### 配置 config.toml

编辑 `~/.codex/config.toml`：

```toml
model_provider = "limapi"
model = "qwen3.8-max"

[model_providers.limapi]
name = "LimAPI"
base_url = "https://limapi.com/api/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

| 字段 | 说明 |
|------|------|
| `base_url` | LimAPI OpenAI 兼容端点，固定为 `https://limapi.com/api/v1` |
| `env_key` | API Key 环境变量名，将 `OPENAI_API_KEY` 设为 Portal 创建的 API Key |
| `wire_api` | LimAPI 网关支持 `responses` 与 `chat` 两种协议；旧版 Codex（如 0.80.0）不支持 Responses API，请改为 `chat` |

### 配置环境变量

在 shell 配置文件（`~/.zshrc` 或 `~/.bashrc`）末尾追加，将 `YOUR_API_KEY` 替换为 Portal 创建的 API Key：

```bash
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc
```

### 配置模型元数据（可选）

使用自定义模型（如 `qwen3.8-max`）时，建议配置模型元数据文件，使 Codex 正确识别模型的上下文窗口、推理深度等参数。

新建文件 `~/.codex/model-catalog.local.json`，写入以下内容：

```json
{
  "models": [
    {
      "slug": "qwen3.8-max",
      "display_name": "qwen3.8-max",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        { "effort": "low", "description": "Fast responses with lighter reasoning" },
        { "effort": "medium", "description": "Greater reasoning depth for complex problems" },
        { "effort": "high", "description": "High reasoning depth for complex problems" }
      ],
      "context_window": 1048576,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": true,
      "input_modalities": ["text", "image"],
      "visibility": "list",
      "supported_in_api": true
    }
  ]
}
```

在 `~/.codex/config.toml` 中添加以下配置，指向元数据文件：

```toml
model_catalog_json = "~/.codex/model-catalog.local.json"
```

如需接入其他模型，在 `models` 数组中以相同格式追加即可，完整列表见 `GET /api/v1/models`。

## 验证

```bash
codex "你好，介绍一下自己"
```

模型正常返回响应即配置成功。

## 常见问题

### 报错 401 / 认证失败

* 确认 `OPENAI_API_KEY` 环境变量已设置且复制完整无空格；
* 修改环境变量后需执行 `source ~/.zshrc` 或新开终端窗口生效。

### 连接异常或无响应

* 确认 `base_url` 以 `/v1` 结尾；
* 若使用旧版 Codex，需将 `wire_api` 改为 `"chat"`。

::: tip 一键配置
使用 [LimAPI Agent 桌面客户端](/agents/limapi-agent) 可自动完成环境变量配置。
:::