# Codex

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

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

> **说明**
>
> 需要先访问 [方舟 Coding Plan活动](https://www.volcengine.com/activity/codingplan)，按需订阅套餐后再配置使用编程工具。

<span id="61e3b838"></span>
# 核心配置

接入工具的核心参数如下：
<span id="3a775131"></span>
## **模型配置**

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

**选项：配置 Model Name (配置文件指定)**

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

> **注意**
>
> 配置 Model Name 时，支持使用全小写格式，同时也支持直接复制 [开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 中的模型名称。

* `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`

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

**选项：配置 ark-code-latest (控制台管理)**

1. 在配置文件中指定模型为`ark-code-latest`。
2. 通过 [开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 选择或切换目标模型，切换模型后 3-5 分钟即可生效。
     支持 Auto 模式，通过「效果 + 速度」双维度智能算法自动选择模型。

<span id="7fd1eee7"></span>
## **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 额度，而是会产生额外费用。

<span id="f05bb565"></span>
## **API Key**

[获取 API Key](https://ark.volcengine.com/region:cn-beijing/apikey)

<span id="ebc4d676"></span>
# Codex CLI

<span id="4dcb69d9"></span>
## 一、安装 Codex CLI

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

前提条件：安装 [Node.js 18 或更新版本](https://nodejs.org/en/download/)。

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

```Bash
npm i -g @openai/codex
```

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

```Bash
codex --version
```

<span id="6d2d0676"></span>
## 二、配置 Codex CLI

<span id="2b5e7a1c"></span>
### 方式 1：自动化助手（推荐）

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

    ![image-20260624-144256-509.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260624-144256-509.png)

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

    1. **选择项目（Project）**：可按需选择，或默认选择**账号全部资源**。
    2. **选择消费模式（Type）**：选择 `coding-plan`。

        ![image-20260624-163746-727.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/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](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260624-163451-813.png)
    3. **选择默认 model**：按需选择。
    4. **选择要配置的 AI Agent**：`Codex`。

        ![](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/arkcli-codex.png)

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

<span id="a1b3c5d7"></span>
### 方式 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`：配置方式参见 [模型配置](/docs/coding-plan-personal-ai-codex#3a775131)。

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

    ```Plain Text
    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`。

3. 配置环境变量，需要将 `ARK_API_KEY` 环境变量设置为 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。

    **选项：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
        ```

<span id="2d7af511"></span>
## 三、开始使用

执行以下命令启动 Codex CLI。

```Bash
codex
```

<span id="e4df2b22"></span>
# Codex 桌面客户端

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

<span id="4af820a5"></span>
## 一、安装 ChatGPT 桌面客户端

从 [OpenAI 官网](https://openai.com/chatgpt/download/) 下载并安装 ChatGPT 桌面客户端。

<span id="3a2d8f9c"></span>
## 二、配置桌面客户端

登录 ChatGPT 桌面客户端后，通过左上角的选项切换 ChatGPT Work 和 Codex，切换到 Codex 模式后，根据以下步骤进行配置。
1. 单击左下角的**设置**。
    ![image-20260630-172328-897.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260630-172328-897.png)
2. 在**配置**页面单击**打开 config.toml**。
    ![image-20260630-172525-618.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260630-172525-618.png)
3. 编辑 `config.toml`，需关注的配置信息如下。

    * `model`：配置方式参见 [模型配置](/docs/coding-plan-personal-ai-codex#3a775131)。

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

        ```Plain Text
        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`。

4. 配置环境变量，需要将 `ARK_API_KEY` 环境变量设置为 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。

    **选项：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
        ```

<span id="ea29a6a0"></span>
## 三、开始使用

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

<span id="c8d4e2f1"></span>
# 使用 Codex 的 Web Search 功能

> **说明**
>
> - 在 Coding Plan 场景下，通过 Responses API 接入的 Codex 也可原生使用 Web Search 功能。
> - 使用豆包搜索承接的 Web Search 会额外发起大模型 API 请求，对搜索结果进行总结。使用前需前往**方舟控制台 > 开通管理 > 应用组件库 > 豆包搜索**启用并开通豆包搜索custom版服务，否则将无法使用 Web Search 功能。

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

1. 登录方舟控制台，打开 [应用组件库 > 豆包搜索](https://ark.volcengine.com/region:cn-beijing/openManagement?advancedActiveKey=component&tab=DoubaoSearch) 标签页。
2. 在**豆包搜索 Custom 版**的**操作**列中点击**开通服务**。

![image-20260922-225128-888.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260922-225128-888.png)

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

<span id="7f95a9e8"></span>
# 错误码

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