文档中心

火山方舟

接入 AI 工具

Codex

本文介绍如何在 Codex 中配置并使用方舟按量计费模型服务。

前提条件

在配置工具前，需要开通所需的模型服务。

Codex CLI

安装 Codex CLI

说明

按量计费模型服务支持 Responses API，可以使用最新版 Codex CLI。

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

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

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

配置 Codex CLI

方式 1：一键配置（推荐）

Ark CLI 是火山方舟平台官方命令行工具，支持在本地终端快速完成认证与资源管理，并可将能力安装到常用 AI Agent 中，降低手动配置的时间成本和出错风险。

安装 Ark CLI

环境要求：Node.js 18 或更新版本。支持 macOS、Linux、Windows。

根据界面提示选择登录方式，推荐选择火山 SSO (浏览器登录)，在浏览器中完成授权即可。

一键配置 Codex

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

选择 Profile：platform_cn-beijing_accountwide。

选择 Endpoint：按需选择要使用的推理接入点。

选择 AI Agent：Codex。

配置完成后，Codex 会自动识别配置的模型。启动 Codex 即可使用。

方式 2：手动配置

新建 ~/.codex/config.toml（Windows 路径：%USERPROFILE%\.codex\config.toml），配置信息如下：

model：按需选择模型并获取 Model ID。可用模型参见模型列表。

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

model = "<MODEL_ID>"
model_provider = "volcengine"

[model_providers.volcengine]
name = "volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"

注意

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

配置完成后，即可使用 Codex CLI。

使用 Codex CLI

执行以下命令启动 Codex CLI。

Codex 桌面客户端

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

安装 ChatGPT 桌面客户端

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

配置桌面客户端

单击左下角的设置。

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

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

model：按需选择模型并获取 Model ID。可用模型参见模型列表。

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

model = "<MODEL_ID>"
model_provider = "volcengine"

[model_providers.volcengine]
name = "volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "ARK_API_KEY"
wire_api = "responses"

注意

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 功能

说明

Codex 通过兼容 OpenAI Responses API 接口协议的服务调用豆包搜索能力。

调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。

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

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

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

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

接入 MCP Server

若内置工具未覆盖您的使用场景，可在 Codex 中接入二方、三方 MCP Server，扩展模型可用的能力。

获取 MCP Server

二方：访问智能体工具商店，获取火山引擎生态内的 MCP 工具（如巨量千川、知识库等），在 MCP 详情页获取服务地址与鉴权信息。

三方：接入其他 MCP 市场提供的 MCP Server，或自行部署开源 MCP Server。

注意

请从可信来源获取 MCP Server，其安全性与稳定性由提供方负责，接入前请确认其权限范围符合您的预期。

配置 MCP Server

编辑 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml），添加 MCP Server 配置。

配置完成后，重启 Codex 后生效。

最近更新时间：2026.11.03 21:11:08

这个页面对您有帮助吗？

有用

无用