面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/coding-plan-personal-ai-codex.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

Codex

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

核心配置#

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

模型配置#

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

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

  • doubao-seed-evolving
  • doubao-seed-2.1-pro
  • doubao-seed-2.1-lite
  • doubao-seed-2.0-mini
  • minimax-m3
  • glm-5.3 (glm-latest)
  • glm-5.3-flash
  • deepseek-v4.1-flash
  • deepseek-v4-flash
  • deepseek-v4-pro
  • kimi-k2.8-preview
  • kimi-k3
  1. 在配置文件中指定模型为ark-code-latest。
  2. 通过 开通管理页面 选择或切换目标模型，切换模型后 3-5 分钟即可生效。
    支持 Auto 模式，通过「效果 + 速度」双维度智能算法自动选择模型。

Base URL#

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

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

API Key#

获取 API Key

Codex CLI#

一、安装 Codex CLI#

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

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

Bash
npm i -g @openai/codex

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

Bash
codex --version

二、配置 Codex CLI#

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

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

  1. 安装 Ark CLI。

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

# 2. 验证安装
arkcli --version

  2. 登录 Ark CLI。

    Bash
    arkcli auth login

    image-20260624-144256-509.png

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

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

    2. 选择消费模式（Type）：选择 coding-plan。

      image-20260624-163746-727.png

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

    1. 在命令行界面输入 arkcli helper 命令，启动 ArkCLI Helper。
    2. 选择要配置的 Plan profile：选择 coding-plan_cn-beijing_personal (Coding Plan)。
      image-20260624-163451-813.png
    3. 选择默认 model：按需选择。
    4. 选择要配置的 AI Agent：Codex。

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

方式 2：手动配置#

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

macOS/Linux 系统 Codex 配置文件路径：~/.codex/config.toml。

  1. 如果在主目录下没有.codex目录，执行以下命令创建目录。

    Bash
    mkdir -p ~/.codex

  2. 创建并打开配置文件。

    Bash
    nano ~/.codex/config.toml

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"

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

    • model：配置方式参见 模型配置。

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

    Plain
    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"
  1. 配置环境变量，需要将 ARK_API_KEY 环境变量设置为 API Key。

  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

  • 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 官网 下载并安装 ChatGPT 桌面客户端。

二、配置桌面客户端#

登录 ChatGPT 桌面客户端后，通过左上角的选项切换 ChatGPT Work 和 Codex，切换到 Codex 模式后，根据以下步骤进行配置。

  1. 单击左下角的设置。
    image-20260630-172328-897.png

  2. 在配置页面单击打开 config.toml。
    image-20260630-172525-618.png

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

    • model：配置方式参见 模型配置。

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

      Plain
      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"
  1. 配置环境变量，需要将 ARK_API_KEY 环境变量设置为 API Key。

  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

  • 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 使用 Web Search 功能。

  1. 登录方舟控制台，打开 应用组件库 > 豆包搜索 标签页。
  2. 在豆包搜索 Custom 版的操作列中点击开通服务。

image-20260922-225128-888.png

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

错误码#

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