Markdown rendered as page contentCodex

Codex 配置

BitCloud API 兼容 OpenAI 协议，支持 Codex CLI 和 IDE 插件，可参考本文进行配置与使用。

前置工作

获取凭证

项目	值
BASE_URL（OpenAI 兼容协议）	`https://web.bitcloud.com.cn/v1`
API Key	格式：`sk-xxxxx`
获取方式	前往控制台 → 令牌管理页面创建

安装 Codex

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

安装命令：

bashnpm install -g @openai/codex

验证安装（如有版本号输出，则表示安装成功）：

bashcodex --version

编辑配置文件

注意： 配置前请检查是否已存在 BITCLOUD_API_KEY 或类似环境变量。如果已存在，请清除或将其值替换为 BitCloud API Key。

注意： 如需通过 /model 命令直接切换模型，请参考下方"自定义模型配置"部分，配置 model-catalogs.json 文件。

配置文件路径：

macOS/Linux： ~/.codex/config.toml
Windows： UserDirectory\.codex\config.toml

以下为完整配置示例。model 字段可更改为其他支持的模型。

编辑或创建 `config.toml`

tomlmodel = "gpt-4o"
model_provider = "bitcloud"
model_reasoning_effort = "high"

# 启用推理摘要；若为 false，model_reasoning_effort 将不生效
model_supports_reasoning_summaries = true
model_reasoning_summary = "none"
model_context_window = 128000

web_search = "disabled"

[model_providers.bitcloud]
name = "bitcloud"
base_url = "https://web.bitcloud.com.cn/v1"
env_key = "BITCLOUD_API_KEY"
wire_api = "responses"

设置 API Key 环境变量

macOS/Linux：

bashecho 'export BITCLOUD_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Windows (CMD)：

cmdsetx BITCLOUD_API_KEY "sk-your-api-key-here"

# 设置成功后，打开新的命令窗口运行：
echo %BITCLOUD_API_KEY%

使用 Codex CLI

配置完成后，打开新终端并启动 Codex：

bashcodex

使用 Codex IDE 插件

VS Code 扩展市场可搜索安装 Codex 扩展。插件会自动复用本地 Codex 的配置。如果从未使用过 CLI 工具，请先按上述步骤配置配置文件。

扩展阅读

自定义模型配置

Codex 允许自定义模型参数，实现对模型的精细化配置。配置完成后，在 Codex CLI 中输入 /model 即可在模型列表中看到可用模型及其推理等级，支持即时切换。

关键配置字段说明

字段	用途
`slug`	内部唯一模型标识符，必须与后端 API 模型名称完全一致
`display_name`	前端显示名称，可与 slug 一致或自定义
`description`	模型介绍文本，用于悬浮提示和详情展示
`default_reasoning_level`	新会话的默认推理强度
`context_window`	标称总上下文窗口大小
`supports_image_detail_original`	图片输入是否支持原始高分辨率解析

配置步骤

1. 编辑或创建 .codex/model-catalogs/model-catalogs.json，进行模型配置：

json{
  "models": [
    {
      "slug": "gpt-4o",
      "display_name": "GPT-4o",
      "description": "OpenAI GPT-4o: 多模态旗舰模型",
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        { "effort": "none", "description": "关闭思考" },
        { "effort": "high", "description": "开启思考" }
      ],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 0,
      "supports_reasoning_summaries": true,
      "default_reasoning_summary": "none",
      "support_verbosity": false,
      "truncation_policy": { "mode": "bytes", "limit": 10000 },
      "supports_parallel_tool_calls": true,
      "supports_image_detail_original": true,
      "context_window": 128000,
      "max_context_window": 128000,
      "effective_context_window_percent": 95,
      "experimental_supported_tools": [],
      "input_modalities": ["text", "image"],
      "supports_search_tool": false
    }
  ]
}

2. 在 config.toml 的根级别添加以下内容：

macOS/Linux：

tomlmodel_catalog_json = "~/.codex/model-catalogs/model-catalogs.json"

Windows：

tomlmodel_catalog_json = "UserDirectory/.codex/model-catalogs/model-catalogs.json"

常见问题

模型名称应该填什么？

BitCloud 支持多种模型，具体可用模型列表请在模型广场查看。常见的模型 ID 包括：

gpt-4o — OpenAI GPT-4o
claude-sonnet-4-20250514 — Anthropic Claude Sonnet
gemini-2.5-pro — Google Gemini 2.5 Pro

配置后请求报错？

请检查：

API Key 是否正确复制（完整密钥，无多余空格）
Base URL 是否以 /v1 结尾
模型名称是否与 BitCloud 平台提供的模型 ID 一致

BitCloud API Documentation