文档中心

火山方舟

接入 AI 工具

Codex

本文介绍如何配置方舟 Agent Plan 到 Codex 中使用。

前提条件

您已按需订阅 Agent Plan 套餐。如未，请访问开通管理-Agent Plan 页面订阅套餐。

Codex CLI

一、安装 Codex CLI

说明

Agent Plan 支持 Responses API，可以使用最新版 Codex CLI。

前提条件：安装 Node.js 18 或更新版本。

在命令行界面，执行以下命令安装 Codex CLI。

安装结束后，执行以下命令检查版本。

二、配置 Codex CLI

方式 1：自动化助手（推荐）

ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Agent Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。

注意

ArkCLI Helper 是基于 Ark Helper 升级演进的工具配置服务，相关能力将持续在 ArkCLI Helper 上迭代更新。建议优先使用 ArkCLI Helper 完成工具配置。

ArkCLI Helper 支持 macOS、Linux、Windows 系统。

安装 Ark CLI。

# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli@latest

# 2. 验证安装
arkcli --version

arkcli auth login

根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 arkcli config reset 后再运行 arkcli auth login。首次登录时，按提示完成以下配置：

选择项目（Project）：可按需选择，或默认选择账号全部资源。

选择消费模式（Type）：选择 agent-plan。

运行 ArkCLI Helper，根据界面提示完成 Codex 的配置。

在命令行界面输入 arkcli helper 命令，启动 ArkCLI Helper。

选择要配置的 Plan profile：agent-plan_cn-beijing_personal (Agent Plan)。

选择默认 model：按需选择。

选择要配置的 AI Agent：Codex。

当前支持的 Harness 包括：豆包搜索、专业数据集、Agent 记忆（OpenViking）、AI Native 应用开发底座，根据界面提示按需选择配置或者跳过。

完成上述操作后，将自动完成 Codex 的基础配置，并按选择结果自动安装对应的 Harness 工具，无需手动安装。

方式 2：手动配置

创建并打开 Codex 的配置文件。文件路径因系统而异，具体操作如下：

macOS/Linux
Windows
macOS/Linux 系统 Codex 配置文件路径：~/.codex/config.toml。
如果在主目录下没有.codex目录，执行以下命令创建目录。

mkdir -p ~/.codex

创建并打开配置文件。

nano ~/.codex/config.toml
Windows 系统 Codex 配置文件路径：%USERPROFILE%\.codex\config.toml。以 CMD 命令行方式为例，操作如下。
如果当前用户目录下没有.codex目录，执行以下命令创建目录。

if not exist "%USERPROFILE%\.codex" mkdir "%USERPROFILE%\.codex"

创建并打开配置文件。

notepad "%USERPROFILE%\.codex\config.toml"

编辑 config.toml，需关注的配置信息如下：

model：需配置文本生成模型。支持配置 ark-code-latest、配置 Model Name。模型信息见支持模型及 Harness。

env_key：设置的是环境变量名称，请不要直接修改 ARK_API_KEY，您需要在下一步设置该环境变量的值。

model = "<Model_Name>"
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。

配置环境变量，需要将 ARK_API_KEY 环境变量设置为专属 API Key。

macOS / Linux
Windows
查看 Shell 类型。

echo $SHELL

将环境变量写入 Shell 配置文件，使其在新开终端时自动生效。
Zsh

# 需要将 YOUR_API_KEY 替换为专属 API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

Bash

# 需要将 YOUR_API_KEY 替换为专属 API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
CMD：环境变量设置完成后，新开 CMD 窗口生效。

# 需要将 YOUR_API_KEY 替换为专属 API Key。
setx ARK_API_KEY "YOUR_API_KEY"
# 新开窗口，检查环境变量是否生效
echo %ARK_API_KEY%

PowerShell：环境变量设置完成后，新开 PowerShell 窗口生效。

# 需要将 YOUR_API_KEY 替换为专属 API Key。
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)
# 新开窗口，检查环境变量是否生效
echo $env:ARK_API_KEY

三、开始使用

执行以下命令启动 Codex CLI。

Codex 桌面客户端

OpenAI 更新后已取消 Codex 的独立应用，将其融入了 ChatGPT Desktop App 作为其中的一个模式。

一、安装 ChatGPT 桌面客户端

从 OpenAI 官网下载并安装 ChatGPT 桌面客户端。

二、配置桌面客户端

单击左下角的设置。

在配置页面单击打开 config.toml。

编辑 config.toml，需关注的配置信息如下。

model：需配置文本生成模型。支持配置 ark-code-latest、配置 Model Name。模型信息见支持模型及 Harness。

env_key：设置的是环境变量名称，请不要直接修改 ARK_API_KEY，您需要在下一步设置该环境变量的值。

model = "<Model_Name>"
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。

配置环境变量，需要将 ARK_API_KEY 环境变量设置为专属 API Key。

macOS / Linux
Windows
查看 Shell 类型。

echo $SHELL

将环境变量写入 Shell 配置文件，使其在新开终端时自动生效。
Zsh

# 需要将 YOUR_API_KEY 替换为专属 API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

Bash

# 需要将 YOUR_API_KEY 替换为专属 API Key。
echo 'export ARK_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
CMD：环境变量设置完成后，新开 CMD 窗口生效。

# 需要将 YOUR_API_KEY 替换为专属 API Key。
setx ARK_API_KEY "YOUR_API_KEY"
# 新开窗口，检查环境变量是否生效
echo %ARK_API_KEY%

PowerShell：环境变量设置完成后，新开 PowerShell 窗口生效。

# 需要将 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 功能。

更多说明参见豆包搜索。

完成配置后，按以下步骤在 Codex 使用 Web Search 功能。

在控制台开启豆包搜索抵扣。

在 Codex 中直接提问，例如"GitHub 最近有哪些热门开源项目"。

最近更新时间：2026.09.28 17:07:22

这个页面对您有帮助吗？

有用

无用