# Codex
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本文介绍如何在 Codex 中配置并使用方舟 按量计费模型服务。
# 前提条件
在配置工具前，需要 [开通所需的模型服务](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)。
# Codex CLI
## 安装 Codex CLI
> **说明**
>
> 按量计费模型服务支持 Responses API，可以使用最新版 Codex CLI。
**前提条件**：安装 [Node.js 18 或更新版本](https://nodejs.org/en/download/)。
在命令行界面，执行以下命令安装 Codex CLI。
```Bash
npm i -g @openai/codex
```
安装结束后，执行以下命令检查版本。
```Bash
codex --version
```
## 配置 Codex CLI
1. 创建并打开 Codex 的配置文件。文件路径因系统而异，具体操作如下：
**选项：macOS/Linux**
macOS/Linux 系统 Codex 配置文件路径：`~/.codex/config.toml`。
1. 如果在主目录下没有`.codex`目录，执行以下命令创建目录。
```Bash
mkdir -p ~/.codex
```
2. 创建并打开配置文件。
```Bash
nano ~/.codex/config.toml
```
**选项：Windows**
Windows 系统 Codex 配置文件路径：`%USERPROFILE%\.codex\config.toml`。以 CMD 命令行方式为例，操作如下。
1. 如果当前用户目录下没有`.codex`目录，执行以下命令创建目录。
```Bash
if not exist "%USERPROFILE%\.codex" mkdir "%USERPROFILE%\.codex"
```
2. 创建并打开配置文件。
```Bash
notepad "%USERPROFILE%\.codex\config.toml"
```
2. 编辑 `config.toml`，需关注的配置信息如下：
* `model`：按需选择模型并获取 Model ID。可用模型参见[模型列表](/docs/model-list)。
* `env_key`：设置的是环境变量名称，请不要直接修改 `ARK_API_KEY`，您需要在下一步设置该环境变量的值。
```Plain Text
model = ""
model_provider = "volcengine"
model_supports_reasoning_summaries = true
[model_providers.volcengine]
name = "volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"
```
> **注意**
>
> * `model_supports_reasoning_summaries = true`：开启推理能力。
> * `model_reasoning_effort`：控制思考长度，可以设置为 `low`、`medium`、`high`。
> * kimi-k2.7-code 不支持设置 `model_supports_reasoning_summaries = true`。
3. 配置环境变量，需要将 `ARK_API_KEY` 环境变量设置为 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
**选项：macOS / Linux**
1. 查看 Shell 类型。
```Bash
echo $SHELL
```
2. 将环境变量写入 Shell 配置文件，使其在新开终端时自动生效。
* Zsh
```Bash
# 将 YOUR_API_KEY 替换为API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc
```
* Bash
```Bash
# 将 YOUR_API_KEY 替换为API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
```
**选项：Windows**
* CMD：环境变量设置完成后，新开 CMD 窗口生效。
```Bash
# 将 YOUR_API_KEY 替换为API Key。
setx ARK_API_KEY "YOUR_API_KEY"
# 新开窗口，检查环境变量是否生效
echo %ARK_API_KEY%
```
* PowerShell：环境变量设置完成后，新开 PowerShell 窗口生效。
```Bash
# 将 YOUR_API_KEY 替换为API Key。
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)
# 新开窗口，检查环境变量是否生效
echo $env:ARK_API_KEY
```
## 使用 Codex CLI
执行以下命令启动 Codex CLI。
```Bash
codex
```
# Codex 桌面客户端
OpenAI 更新后已取消 Codex 的独立应用，将其融入了 ChatGPT Desktop App 作为其中的一个模式。
## 安装 ChatGPT 桌面客户端
从 [OpenAI 官网](https://openai.com/chatgpt/download/) 下载并安装 ChatGPT 桌面客户端。
## 配置桌面客户端
登录 ChatGPT 桌面客户端后，通过左上角的选项切换 ChatGPT Work 和 Codex，切换到 Codex 模式后，根据以下步骤进行配置。
1. 单击左下角的**设置**。
2. 在**配置**页面单击**打开 config.toml**。
3. 编辑 `config.toml`，需关注的配置信息如下。
* `model`：按需选择模型并获取 Model ID。可用模型参见[模型列表](/docs/model-list)。
* `env_key`：设置的是环境变量名称，请不要直接修改 `ARK_API_KEY`，您需要在下一步设置该环境变量的值。
```Plain Text
model = ""
model_provider = "volcengine"
model_supports_reasoning_summaries = true
[model_providers.volcengine]
name = "volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"
```
> **注意**
>
> * `model_supports_reasoning_summaries = true`：开启推理能力。
> * `model_reasoning_effort`：控制思考长度，可以设置为 `low`、`medium`、`high`。
> * kimi-k2.7-code 不支持设置 `model_supports_reasoning_summaries = true`。
4. 配置环境变量，需要将 `ARK_API_KEY` 环境变量设置为 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
**选项：macOS / Linux**
1. 查看 Shell 类型。
```Bash
echo $SHELL
```
2. 将环境变量写入 Shell 配置文件，使其在新开终端时自动生效。
* Zsh
```Bash
# 将 YOUR_API_KEY 替换为API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc
```
* Bash
```Bash
# 将 YOUR_API_KEY 替换为API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
```
**选项：Windows**
* CMD：环境变量设置完成后，新开 CMD 窗口生效。
```Bash
# 将 YOUR_API_KEY 替换为API Key。
setx ARK_API_KEY "YOUR_API_KEY"
# 新开窗口，检查环境变量是否生效
echo %ARK_API_KEY%
```
* PowerShell：环境变量设置完成后，新开 PowerShell 窗口生效。
```Bash
# 将 YOUR_API_KEY 替换为API Key。
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)
# 新开窗口，检查环境变量是否生效
echo $env:ARK_API_KEY
```
## 使用桌面客户端
配置完成后，需要退出 ChatGPT 桌面客户端并重新打开让配置生效。重新启动后，即可在对话界面中使用。
# 使用 Codex 的 Web Search 功能
> **说明**
>
> * Codex 通过兼容 OpenAI Responses API 接口协议的服务调用豆包搜索能力。
> * 调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
完成配置后，按以下步骤在 Codex 使用 Web Search 功能。
1. 登录方舟控制台，打开 [应用组件库 > 豆包搜索](https://ark.volcengine.com/region:cn-beijing/openManagement?advancedActiveKey=component&tab=DoubaoSearch) 标签页。
2. 在**豆包搜索 Custom 版**的**操作**列中点击**开通服务**。
3. 在 Codex 中直接提问，例如"GitHub 最近有哪些热门开源项目"。
# 接入 MCP Server
若内置工具未覆盖您的使用场景，可在 Codex 中接入二方、三方 MCP Server，扩展模型可用的能力。
## 获取 MCP Server
* **二方**：访问 [智能体工具商店](https://www.volcengine.com/mcp-marketplace)，获取火山引擎生态内的 MCP 工具（如巨量千川、知识库等），在 MCP 详情页获取服务地址与鉴权信息。
* **三方**：接入其他 MCP 市场提供的 MCP Server，或自行部署开源 MCP Server。
> **注意**
>
> 请从可信来源获取 MCP Server，其安全性与稳定性由提供方负责，接入前请确认其权限范围符合您的预期。
## 配置 MCP Server
编辑 `~/.codex/config.toml`（Windows 为 `%USERPROFILE%\.codex\config.toml`），添加 MCP Server 配置。
```Plain Text
[mcp_servers.]
command = "<启动命令>"
args = ["<启动参数>"]
```
配置完成后，重启 Codex 后生效。