文档中心

火山方舟

接入 AI 工具

Codex

本文介绍如何配置方舟 Coding Plan 个人版到 Codex CLI 中使用。

说明

需要先访问方舟 Coding Plan活动，按需订阅套餐后再配置使用编程工具。

核心配置

接入工具的核心参数如下：

模型配置

支持以下两种方式配置模型：

配置 Model Name (配置文件指定)

配置 ark-code-latest (控制台管理)

在工具配置文件中指定 Model Name，可实时切换模型。支持配置的 Model Name：

注意

配置 Model Name 时，支持使用全小写格式，同时也支持直接复制中的模型名称。

doubao-seed-evolving

doubao-seed-2.1-pro

doubao-seed-2.1-lite

doubao-seed-2.0-mini

glm-5.3 (glm-latest)

glm-5.3-flash

deepseek-v4.1-flash

deepseek-v4.1-flash-economy

deepseek-v4-flash

deepseek-v4-pro

kimi-k2.8-preview

kimi-k3

kimi-k3.1-pro

说明

Model Name 不支持配置为 Auto，如需使用，请通过控制台切换该模式。

Base URL

不同的工具配置的 Base URL 根据兼容的协议会有不同：

兼容 Anthropic 接口协议工具：https://ark.cn-beijing.volces.com/api/coding

兼容 OpenAI 接口协议工具：https://ark.cn-beijing.volces.com/api/coding/v3

注意

请勿使用 https://ark.cn-beijing.volces.com/api/v3 ：该 Base URL 不会消耗您的 Coding Plan 额度，而是会产生额外费用。

API Key

获取 API Key

Codex CLI

一、安装 Codex CLI

说明

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

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

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

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

二、配置 Codex CLI

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

ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Coding 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）：选择 coding-plan。

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

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

选择要配置的 Plan profile：选择 coding-plan_cn-beijing_personal (Coding Plan)。

选择默认 model：按需选择。

选择要配置的 AI Agent：Codex。

完成上述操作后，将自动完成 Codex 的基础配置，无需手动安装。

方式 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：配置方式参见模型配置。

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

model = "<Model_Name>"
model_provider = "volcengine-coding-plan"
model_supports_reasoning_summaries = true

[model_providers.volcengine-coding-plan]
name = "volcengine-coding-plan"
base_url = "https://ark.cn-beijing.volces.com/api/coding/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：配置方式参见模型配置。

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

model = "<Model_Name>"
model_provider = "volcengine-coding-plan"
model_supports_reasoning_summaries = true

[model_providers.volcengine-coding-plan]
name = "volcengine-coding-plan"
base_url = "https://ark.cn-beijing.volces.com/api/coding/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

三、开始使用

配置完成后，需要退出 ChatGPT 桌面客户端并重新打开让配置生效。重新启动后，即可在对话界面中使用。

使用 Codex 的 Web Search 功能

说明

在 Coding Plan 场景下，通过 Responses API 接入的 Codex 也可原生使用 Web Search 功能。

使用豆包搜索承接的 Web Search 会额外发起大模型 API 请求，对搜索结果进行总结。使用前需前往方舟控制台 > 开通管理 > 应用组件库 > 豆包搜索启用并开通豆包搜索custom版服务，否则将无法使用 Web Search 功能。

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

登录方舟控制台，打开应用组件库 > 豆包搜索标签页。

在豆包搜索 Custom 版的操作列中点击开通服务。

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

错误码

在编程工具中使用 Coding Plan 套餐时可能会遇到报错，您可以根据错误信息查看对应的报错场景并定位问题，具体可参考错误码。

最近更新时间：2026.10.24 20:26:04

这个页面对您有帮助吗？

有用

无用