# Codex
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本文介绍如何配置方舟 Agent Plan 到 Codex 中使用。
# 前提条件
您已按需订阅 Agent Plan 套餐。如未，请访问 [开通管理-Agent Plan](https://ark.volcengine.com/region:cn-beijing/openManagement?advancedActiveKey=agentPlan) 页面订阅套餐。
# Codex CLI
## 一、安装 Codex CLI
> **说明**
>
> Agent Plan 支持 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：自动化助手（推荐）
ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Agent Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。
> **注意**
>
> * ArkCLI Helper 是基于 Ark Helper 升级演进的工具配置服务，相关能力将持续在 ArkCLI Helper 上迭代更新。建议优先使用 ArkCLI Helper 完成工具配置。
> * ArkCLI Helper 支持 macOS、Linux、Windows 系统。
1. 安装 Ark CLI。
```Bash
# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli@latest
# 2. 验证安装
arkcli --version
```
2. 登录 Ark CLI。
```Bash
arkcli auth login
```
根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 `arkcli config reset` 后再运行 `arkcli auth login`。首次登录时，按提示完成以下配置：
1. **选择项目（Project）**：可按需选择，或默认选择**账号全部资源**。
2. **选择消费模式（Type）**：选择 `agent-plan`。
3. 运行 ArkCLI Helper，根据界面提示完成 Codex 的配置。
1. 在命令行界面输入 `arkcli helper` 命令，启动 ArkCLI Helper。
2. **选择要配置的 Plan profile**：`agent-plan_cn-beijing_personal (Agent Plan)`。
3. **选择默认 model**：按需选择。
4. **选择要配置的 AI Agent**：`Codex`。
当前支持的 Harness 包括：豆包搜索、专业数据集、Agent 记忆（OpenViking）、AI Native 应用开发底座，根据界面提示按需选择`配置`或者`跳过`。
完成上述操作后，将自动完成 Codex 的基础配置，并按选择结果自动安装对应的 Harness 工具，无需手动安装。
### 方式 2：手动配置
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`：需配置文本生成模型。支持配置 `ark-code-latest`、配置 Model Name。模型信息见[支持模型及 Harness](/docs/agent-plan-personal-plan-overview#3d801f5f)。
* `env_key`：设置的是环境变量名称，请不要直接修改 `ARK_API_KEY`，您需要在下一步设置该环境变量的值。
```Plain Text
model = ""
model_provider = "volcengine-agent-plan"
model_supports_reasoning_summaries = true
[model_providers.volcengine-agent-plan]
name = "volcengine-agent-plan"
base_url = "https://ark.cn-beijing.volces.com/api/plan/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/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan)。
**选项：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。
```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`：需配置文本生成模型。支持配置 `ark-code-latest`、配置 Model Name。模型信息见[支持模型及 Harness](/docs/agent-plan-personal-plan-overview#3d801f5f)。
* `env_key`：设置的是环境变量名称，请不要直接修改 `ARK_API_KEY`，您需要在下一步设置该环境变量的值。
```Plain Text
model = ""
model_provider = "volcengine-agent-plan"
model_supports_reasoning_summaries = true
[model_providers.volcengine-agent-plan]
name = "volcengine-agent-plan"
base_url = "https://ark.cn-beijing.volces.com/api/plan/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"
```
> **注意**
>
> * `model_supports_reasoning_summaries = true`：开启推理能力。
> * `model_reasoning_effort`：控制思考长度，可以设置为 `low`、`medium`、`high`。
4. 配置环境变量，需要将 `ARK_API_KEY` 环境变量设置为 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan)。
**选项：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 功能
> **说明**
>
> - 除了通过配置 MCP 或 Skill 使用豆包搜索能力外，在 Agent Plan 场景下，通过 Responses API 接入的 Codex 也可原生使用 Web Search 功能。
> - 使用豆包搜索承接的 Web Search 会额外发起大模型 API 请求，对搜索结果进行总结。使用前需前往控制台开启豆包搜索抵扣，否则将无法使用 Web Search 功能。
> - 更多说明参见 [豆包搜索](/docs/agent-plan-personal-search)。
完成配置后，按以下步骤在 Codex 使用 Web Search 功能。
1. 在控制台开启豆包搜索抵扣。
2. 在 Codex 中直接提问，例如"GitHub 最近有哪些热门开源项目"。