跳转到主要内容
接入AI工具

Codex

在 Codex 中使用千问AI平台模型

Codex 是 OpenAI 推出的终端 AI 编程助手。可通过 Token Plan 个人版、Token Plan 团队版或按量计费接入千问AI平台。
qwen4-max 的上下文长度为 1M Token;非思考模式最大输出 131,072 Token,思考与最终回答合计最大 262,144 Token;默认 reasoning_effort=high,thinking_budget=131072。可通过 codex -m qwen4-max 指定模型。

快速开始

1

打开或新建配置文件

  • macOS / Linux:~/.codex/config.toml
  • Windows:C:\Users\<用户名>\.codex\config.toml
2

配置模型

如需在模型间切换,参见配置模型元数据。
  • Token Plan
  • 按量计费
将 OPENAI_API_KEY 替换为 Token Plan API Key:
model_provider = "Token_Plan"
model = "auto"

[model_providers.Token_Plan]
name = "Token_Plan"
base_url = "https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
3

验证

在项目目录中运行以下命令:
codex exec "你好"

配置模型元数据

模型元数据用于在 Codex 中切换模型。不配置时,config.toml 中指定的模型仍可正常调用,但启动时会提示 Model metadata ... not found,Codex 按默认元数据处理模型。配置后,可通过 codex -m 或 TUI 的 /model 在模型间切换。
  • Token Plan 个人版
  • Token Plan 团队版
  • 按量计费
新建 ~/.codex/model-catalog.local.json,写入以下内容:
{
  "models": [
    {
      "slug": "auto",
      "display_name": "auto",
      "description": "DashScope model: auto",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 1,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen4-max",
      "display_name": "qwen4-max",
      "description": "Qianwen AI Platform model: qwen4-max",
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "high",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 2,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen4-max-preview",
      "display_name": "qwen4-max-preview",
      "description": "DashScope model: qwen4-max-preview",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 2,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.8-max",
      "display_name": "qwen3.8-max",
      "description": "DashScope model: qwen3.8-max",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 983616,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 3,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.8-flash",
      "display_name": "qwen3.8-flash",
      "description": "DashScope model: qwen3.8-flash",
      "default_reasoning_level": "xhigh",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 983616,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 4,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.7-max",
      "display_name": "qwen3.7-max",
      "description": "DashScope model: qwen3.7-max",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 5,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.7-plus",
      "display_name": "qwen3.7-plus",
      "description": "DashScope model: qwen3.7-plus",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 6,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "qwen3.6-flash",
      "display_name": "qwen3.6-flash",
      "description": "DashScope model: qwen3.6-flash",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 7,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "glm-5.3",
      "display_name": "glm-5.3",
      "description": "DashScope model: glm-5.3",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 8,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "glm-5.2",
      "display_name": "glm-5.2",
      "description": "DashScope model: glm-5.2",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 9,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4.1-flash",
      "display_name": "deepseek-v4.1-flash",
      "description": "DashScope model: deepseek-v4.1-flash",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 10,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4.1-flash-1017",
      "display_name": "deepseek-v4.1-flash-1017",
      "description": "DashScope model: deepseek-v4.1-flash-1017",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": true,
      "input_modalities": [
        "text",
        "image"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 11,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4-pro",
      "display_name": "deepseek-v4-pro",
      "description": "DashScope model: deepseek-v4-pro",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 12,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4-pro-0813",
      "display_name": "deepseek-v4-pro-0813",
      "description": "DashScope model: deepseek-v4-pro-0813",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 13,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    },
    {
      "slug": "deepseek-v4-flash-0731",
      "display_name": "deepseek-v4-flash-0731",
      "description": "DashScope model: deepseek-v4-flash-0731",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        },
        {
          "effort": "xhigh",
          "description": "Extra high reasoning depth for complex problems"
        }
      ],
      "context_window": 1000000,
      "effective_context_window_percent": 95,
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "input_modalities": [
        "text"
      ],
      "shell_type": "default",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 14,
      "base_instructions": "",
      "support_verbosity": false,
      "supports_reasoning_summaries": false,
      "experimental_supported_tools": [],
      "truncation_policy": {
        "mode": "bytes",
        "limit": 10000
      }
    }
  ]
}
在 ~/.codex/config.toml 中添加:
model_catalog_json = "~/.codex/model-catalog.local.json"
配置完成后,可通过 codex -m 指定模型 ID(例如 codex -m qwen3.8-flash),或在 TUI 中输入 /model 在已配置的模型间切换。

Chat Completions 配置

Codex 0.94.0 起只支持 Responses API。如果使用 Codex 0.93.0 或更早版本,或所用模型只支持 Chat Completions,请按以下方式配置。
1

打开或新建配置文件

  • macOS / Linux:~/.codex/config.toml
  • Windows:C:\Users\<用户名>\.codex\config.toml
2

写入配置

  • Token Plan
  • 按量计费
将 OPENAI_API_KEY 替换为 Token Plan API Key:
model_provider = "Token_Plan"
model = "auto"

[model_providers.Token_Plan]
name = "Token_Plan"
base_url = "https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

使用 CC Switch

CC Switch 是社区开源的桌面 GUI,支持在多个 API Key 或计费套餐之间一键切换。

添加供应商

1

添加供应商

在 CC Switch 主界面顶部图标栏选中 Codex 图标,点击右上角 + 进入添加新供应商,按对应 Tab 填入配置后点击添加。
  • Token Plan
  • 按量计费
  • 供应商名称:千问AI平台-Token Plan
  • API Key:控制台获取
  • 请求地址:https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1
2

填写模型名称

展开高级选项填写模型名称,从对应套餐支持的模型中选择,例如 qwen3.8-max。
3

启用供应商

回到主界面,点击该供应商右侧启用按钮,然后重新打开终端窗口执行 codex 使配置生效。

错误码

配置过程中遇到报错,参考对应计费方案的常见问题文档:

常见问题

这是未配置模型元数据时的提示。Codex 按默认元数据处理模型,不影响调用。如需在模型间切换,参见配置模型元数据。
原因:部分第三方管理工具(如 CC-Switch)在切换供应商时会发起“健康检查/连接测试”探测请求,该探测请求的格式与 Codex 实际调用的请求格式不同,千问AI平台网关可能因此返回 400 Bad request 并提示“检查被拒”,工具据此显示“不支持国内模型”。此提示仅代表健康检查探测未通过,并不代表千问AI平台不支持国内模型,也不影响 Codex 的实际使用。解决方案:参照上文快速开始,直接在 ~/.codex/config.toml 中完成配置,无需依赖第三方工具的健康检查结果。配置完成后按验证启动 Codex,能正常返回响应即表示可正常使用国内模型。
原因:Codex 0.94.0 起不再支持 wire_api = "chat" 配置。根据版本不同,可能出现以下报错:
  • wire_api = "chat" is no longer supported
  • unknown configuration field wire_api
解决方案:
  • 报错 wire_api = "chat" is no longer supported:将 wire_api 改为 responses,并确认 base_url 配置正确。
  • 报错 unknown configuration field wire_api:从 ~/.codex/config.toml 的对应 provider 节中删除 wire_api 字段。
  • 需要继续使用 Chat Completions 时,安装 Codex 0.93.0 或更早版本(如 0.80.0)。
原因:
  • 误用了其他方案的 API Key(Token Plan 个人版、Token Plan 团队版和按量计费的 API Key 互不相通)
  • 订阅过期
  • API Key 复制不完整、有空格或拼写错误
解决方案:
  • 确认使用的是所选方案对应的专属 API Key。
  • 前往对应方案的管理页面确认订阅是否过期。
  • 重新复制 API Key,确保完整且无空格。
  • 如以上均正常仍报错,可在对应管理页面重置 API Key,重置后使用新 API Key 配置。
原因:配置文件中的 base_url 或 wire_api 填写错误。解决方案:确认 base_url 和 wire_api 与所选方案的配置一致,参见快速开始。
原因:Codex 与服务端的流式连接在响应完成前断开。常见于以下场景:
  • 对话线程过长,Codex 触发上下文压缩时请求失败
  • 网络不稳定,SSE 或 WebSocket 连接中途断开
  • 服务端过载或触发限流,提前终止连接
解决方案:
  • 开启新的对话线程,避免单个线程积累过多上下文。
  • 检查网络连接是否稳定,关闭 VPN 或代理后重试。
  • 等待一段时间后重试,Codex 内置了自动重试机制,多数情况下重试可恢复。
原因:429 错误有以下两种情形:
  • 请求超频(429 Requests rate limit exceeded):短时间内请求过于密集。
  • 限额用尽(429 Allocated quota exceeded 或 Your token-plan quota has been exhausted):Token Plan 套餐月额度用尽。
解决方案:
  • 请求超频:等待一分钟后重试,降低请求频率。
  • 限额用尽:等待下一个订阅月额度自动重置;或购买用量包(套餐月额度用尽后自动抵扣用量包额度);或升级套餐。报错信息中的重置时间(如 The quota will reset at HH:MM:SS UTC)以协调世界时(UTC)为准,换算为 UTC+8 需加 8 小时。