# Codex 添加模型:保留原有选项 适用于通过 FlowVision Responses 接口使用模型的 Codex 客户端。以下命令使用 macOS/Linux 的 shell、Node.js 和支持 `codex debug models` 的 Codex CLI。先运行 `codex debug models --help` 确认当前版本支持;若不支持,请更新客户端后再操作。 模型菜单与中转站可用模型列表独立。添加目录只增加选项,不授予权限,也不保证工具调用兼容。DeepSeek、GLM、Qwen、Kimi 都应先确认准确模型 ID、令牌分组权限和渠道的 Responses 支持。不要直接把品牌名作为模型 ID。 ## 1. 查询可用模型 使用与 Codex 相同的 FlowVision API Key。已有其他环境变量时,替换下面的变量名。不要使用上游渠道密钥,也不要把密钥写进模型目录。 ```sh curl --fail-with-body https://api.flowvision.tech/v1/models \ -H "Authorization: Bearer $FLOWVISION_API_KEY" ``` 若返回 401,请检查 Codex provider 的 `env_key` 指向哪个环境变量;不要直接假定 `auth.json` 中的凭据就是当前 provider 的凭据。若没有所需模型,先在中转站接入渠道并开放当前分组权限。 ## 2. 导出原有模型,准备新增目录 ```sh mkdir -p "$HOME/.codex" codex debug models --bundled > "$HOME/.codex/models-bundled.json" ``` 如果 `~/.codex/config.toml` 已有顶层 `model_catalog_json`,必须把它指向的现有目录作为下面的第三个输入一起合并。已有目录、内置目录以及新增目录均采用 `{ "models": [...] }` 格式。 将准备好的新增条目保存为 `~/.codex/models-additions.json`。本项目提供 `docs/examples/codex-deepseek-models.json` 作为结构示例,其中型号和思考档位只适用于相应渠道;先对照 `/v1/models` 核实,不要当作所有用户都可调用的列表。 条目中 `slug` 必须是准确模型 ID;`display_name` 是菜单名称;`visibility` 为 `list`;`supported_in_api` 为 `true`。其他字段必须匹配客户端结构和真实模型能力。GLM、Qwen、Kimi 不要直接复制 GPT 的上下文长度、图片能力、工具能力或推理档位;应使用已验证的模型元数据。 ## 3. 合并目录,按 slug 去重 下面的脚本保留原有条目。重复 slug 优先保留旧条目;最后一份输入仅追加新型号。若有现有自定义目录,在 bundled 与 additions 之间加入它的绝对路径。 ```sh node --input-type=module - "$HOME/.codex/models-bundled.json" "$HOME/.codex/models-additions.json" <<'JS' import fs from 'node:fs' import path from 'node:path' const inputs = process.argv.slice(2) const models = new Map() for (const file of inputs) { const catalog = JSON.parse(fs.readFileSync(file, 'utf8')) if (!Array.isArray(catalog.models)) throw new Error(`Invalid catalog: ${file}`) for (const model of catalog.models) { if (typeof model.slug !== 'string' || !model.slug.trim()) throw new Error(`Missing slug: ${file}`) if (!models.has(model.slug)) models.set(model.slug, model) } } const target = path.join(process.env.HOME, '.codex', 'flowvision-models.json') if (fs.existsSync(target)) fs.copyFileSync(target, `${target}.backup-${Date.now()}`) fs.writeFileSync(target, JSON.stringify({ models: [...models.values()] }, null, 2) + '\n') console.log(`Saved ${models.size} models to ${target}`) JS ``` 若已有自定义目录希望保留同名条目的定制元数据,应把该目录放在 bundled 之前。也可加入模型缓存目录补齐缓存中的独有型号,但不要用旧缓存覆盖新版本内置条目。 ## 4. 校验并启用 ```sh codex debug models -c "model_catalog_json=\"$HOME/.codex/flowvision-models.json\"" cp -p "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)" ``` 确认解析成功、原有和新增型号都在输出中,再编辑 `~/.codex/config.toml`,在第一个 `[section]` 之前添加或更新唯一的顶层配置: ```toml model_catalog_json = "/你的用户目录/.codex/flowvision-models.json" ``` 必须填写实际绝对路径,不要照抄占位符。保留现有 `model`、`model_provider`、provider 的 `base_url`、`wire_api = "responses"` 和认证配置;不必切换默认 GPT 模型。不要在 provider 段落内部添加该字段。 完整退出并重新启动 Codex,在新对话的模型选择器中查看。桌面端和 CLI 若使用不同配置目录或不同版本,需要分别确认它们实际读取的配置及目录结构。 ## 5. 验收与恢复 部署方舟 DeepSeek V4 原生 Responses 兼容后,渠道账号已开通搜索的用户可以直接启动 `codex` 并选择 DeepSeek。模型目录使用 `"supports_search_tool": true`;不要配置 `web_search = "disabled"`。网关保留联网搜索和已声明的编程工具,不要求特殊启动参数。 若之前使用 `codex -p deepseek` 且其独立配置禁用了搜索,请改回直接运行 `codex`, 或取消该独立配置中的搜索禁用项。已经在基础配置中禁用搜索的用户也需恢复客户端搜索; 网关不能替客户端主动开启未声明的工具。 错误排查: - `ToolNotOpen`:在渠道所属火山账号开通联网搜索,开通地址为 https://console.volcengine.com/common-buy/CC_content_plugin 。 - `web_search ... must be function`:检查网关是否已部署原生 Responses 修复, 上游请求不应因 Codex 工具而转发到 Chat Completions。 - `unknown tool type: tool_search`:检查工具发现兼容是否已部署。工具发现与联网搜索 不同;网关使已声明的工具立即可用,但不支持未提供定义的外部动态工具发现。 1. 确认原有 GPT 选项仍在,新型号可以选择。 2. 测试简单文本,再测试只读文件工具以及工具结果回传后的继续回答。 3. 对已确认支持的推理档位逐项测试,并检查使用日志。参数被接受不代表各档位一定有不同计算预算。 4. 新模型返回 403 或无可用渠道时,检查令牌分组、模型权限及渠道;流式或工具报错时检查协议适配。 方舟 DeepSeek 使用原生 Responses;其他 DeepSeek 专用渠道仍可能根据工具选择 Chat 转换路径。Chat 转换路径不支持 `previous_response_id` 等服务端会话状态,需要完整历史;不要把旧的加密推理历史作为首次测试对话。 恢复时将备份配置还原,并在原来已使用目录的情况下还原相应目录备份。自定义目录是静态快照,升级 Codex 后建议重新导出内置目录、合并并校验,以保留新增加的官方模型。