> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> 在 Codex 中使用 GLM Coding Plan 的方法

Codex 是 OpenAI 推出的 AI 编程智能体，能帮你编写、审查和调试代码，支持在终端和桌面应用中使用。

<Warning>
  Codex 需要配置专属的 OpenAI Response 协议端点 `https://open.bigmodel.cn/api/v1`。
</Warning>

## 一、安装 Codex

Codex 提供两种使用形态：在终端中运行的 **Codex CLI**，以及桌面端的 **Codex 应用**。您可以根据使用习惯选择其中一种安装。

<Tabs>
  <Tab title="安装 Codex 应用">
    1. 访问 [ChatGPT 下载页](https://www.chatgpt.com/download)，根据您的操作系统下载对应安装包。
    2. 按照系统提示完成安装并启动应用。
    3. 若您已安装 Codex CLI，也可以在终端中运行以下命令直接启动桌面应用：
       ```
       codex app
       ```
  </Tab>

  <Tab title="安装 Codex CLI">
    前提条件：

    * 您需要安装 [Node.js 18 或更新版本环境](https://nodejs.org/en/download/)
    * macOS 用户推荐使用 [nvm 方式安装 Node.js](https://nodejs.org/en/download/) 不推荐直接安装包安装(后续可能会遇到权限问题)

    进入命令行界面，安装 Codex CLI

    ```
    npm install -g @openai/codex
    ```

    运行如下命令，查看安装结果，若显示版本号则表示安装成功

    ```
    codex --version
    ```
  </Tab>
</Tabs>

## 二、配置 GLM Coding Plan

<Steps>
  <Step title="注册账号">
    访问 [智谱开放平台](https://open.bigmodel.cn)，点击右上角的「注册/登录」按钮，按照提示完成账号注册流程。
  </Step>

  <Step title="获取API Key">
    * 个人版套餐的用户，通过 [个人编程套餐 > 套餐概览](https://bigmodel.cn/coding-plan/personal/overview)，新建  API Key
    * 团队版套餐的成员，通过 [团队编程套餐 > 我的套餐](http://bigmodel.cn/coding-plan?z_plan=team)，获取  API Key（团队套餐 Key 与平台其他 API Key 不通用，使用团队额度请务必使用团队套餐 Key）

    <Warning>
      请妥善保管您的 API Key，不要泄露给他人，也不要直接硬编码在代码中。
    </Warning>
  </Step>

  <Step title="配置模型与 API Key">
    Codex 使用 OpenAI Response 协议接入，对应端点 `https://open.bigmodel.cn/api/v1`。

    <Tip>
      选择以下适合您的一种方式进行配置即可。
    </Tip>

    <Tabs>
      <Tab title="方式一：手动配置">
        支持 macOS & Linux & Windows, 注意不同系统配置文件路径不一样。注意需保证修改的文件格式正确性。

        #### 1. 创建模型目录文件

        创建 `~/.codex/models.json`，向 Codex 声明 GLM 模型的元数据。若文件或目录不存在，请先创建：

        将以下内容完整复制并写入 `~/.codex/models.json`：

        ```json theme={null}
        {
            "models": [
                {
                    "slug": "glm-5.3",
                    "display_name": "glm-5.3",
                    "description": "Z.ai's latest flagship model",
                    "default_reasoning_level": "max",
                    "supported_reasoning_levels": [
                        {
                            "effort": "low",
                            "description": "Light reasoning"
                        },
                        {
                            "effort": "high",
                            "description": "Enhanced reasoning"
                        },
                        {
                            "effort": "max",
                            "description": "Deep reasoning"
                        }
                    ],
                    "shell_type": "shell_command",
                    "visibility": "list",
                    "supported_in_api": true,
                    "priority": 0,
                    "base_instructions": "",
                    "supports_reasoning_summaries": true,
                    "default_reasoning_summary": "none",
                    "support_verbosity": false,
                    "apply_patch_tool_type": "freeform",
                    "truncation_policy": {
                        "mode": "bytes",
                        "limit": 10000
                    },
                    "context_window": 1048576,
                    "max_context_window": 1048576,
                    "effective_context_window_percent": 95,
                    "supports_parallel_tool_calls": true,
                    "experimental_supported_tools": [],
                    "input_modalities": [
                        "text"
                    ]
                },
                {
                    "slug": "glm-5-turbo",
                    "display_name": "glm-5-turbo",
                    "description": "Agent-optimized model",
                    "default_reasoning_level": "max",
                    "supported_reasoning_levels": [],
                    "shell_type": "shell_command",
                    "visibility": "list",
                    "supported_in_api": true,
                    "priority": 1,
                    "base_instructions": "",
                    "supports_reasoning_summaries": true,
                    "default_reasoning_summary": "none",
                    "support_verbosity": false,
                    "apply_patch_tool_type": "freeform",
                    "truncation_policy": {
                        "mode": "bytes",
                        "limit": 10000
                    },
                    "context_window": 204800,
                    "max_context_window": 204800,
                    "effective_context_window_percent": 95,
                    "supports_parallel_tool_calls": true,
                    "experimental_supported_tools": [],
                    "input_modalities": [
                        "text"
                    ]
                }
            ]
        }
        ```

        #### 2. 配置 API Key 与模型

        找到 Codex 的配置文件，配置文件路径如下，配置文件不存在时新建即可：

        * macOS/Linux：`~/.codex/config.toml`
        * Windows：`C:\Users\<用户名>\.codex\config.toml`

        完整复制以下内容并粘贴到 `~/.codex/config.toml` 中，注意将 `<Your API Key>` 替换为您上一步获取的 API Key：

        ```toml theme={null}
        model_provider = "ZAI"
        model = "glm-5.3"
        model_reasoning_effort = "max"
        model_catalog_json = "~/.codex/models.json"

        [model_providers.ZAI]
        name = "ZAI"
        base_url = "https://open.bigmodel.cn/api/v1"
        experimental_bearer_token = "<Your API Key>"
        wire_api = "responses"
        ```

        <Note>
          * `wire_api` 必须为 `responses`。
          * `model_catalog_json` 指向上一步创建的模型元数据文件。
          * `model` 可按需切换为 `glm-5.3` 等已在 `models.json` 中声明的模型。
        </Note>
      </Tab>

      <Tab title="方式二：自动化助手">
        Coding Tool Helper 是一个编码工具助手，快速将您的**GLM编码套餐**加载到 `Codex` 中。安装并运行它，按照界面提示操作即可自动完成工具安装，套餐配置等。

        ```bash theme={null}
        # 进入命令行界面，执行如下运行 Coding Tool Helper
        npx @z_ai/coding-helper
        ```

        详细说明请参考 [Coding Tool Helper 文档](/cn/coding-plan/extension/coding-tool-helper)。
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 三、开始使用 Codex

配置完成后，重启您的 `Codex 应用` 或打开新终端中执行 `codex` 命令即可开始。

## 四、常见问题

### 手工修改配置不生效

* 关闭所有 Codex 窗口，重新打开一个新的命令行窗口，再次运行 `codex` 启动。
* 确认 `~/.codex/models.json` 文件存在且 JSON 格式正确，可使用在线 JSON 校验工具检查。
* 确认 `~/.codex/config.toml` 中的 `model_catalog_json` 路径指向正确。
* 确认 `experimental_bearer_token` 已替换为您实际的 API Key。
* 确认配置文件的 TOML 格式是否正确，检查字段名称、引号、中括号是否完整。