⌘K

Codex

概述

Codex 是 OpenAI 推出的命令行 AI 编程助手, 可在本地项目中读取代码、修改文件、运行命令并协助完成开发任务. 将 Codex 的模型服务配置为 Vtrix 后, 可通过统一入口使用 GPT 系列模型.

环境要求

  • Node.js 18 及以上
  • Codex CLI
  • Vtrix API Key, 在 设置 中创建

配置步骤

1

安装 Codex

• 使用 npm

npm install -g @openai/codex

安装完成后可运行：

codex --version

确认 Codex 已正确安装.

2

配置 Vtrix API

Codex 通过 ~/.codex/config.toml 读取模型服务配置. 这里需要把默认模型服务商切换为 vtrix, 并让 Codex 从环境变量 VTRIX_API_KEY 读取密钥.

• 创建配置目录

mkdir -p ~/.codex

• 设置 API Key

在 ~/.bashrc 或 ~/.zshrc 中加入：

export VTRIX_API_KEY="sk-xxxxxxx"

修改后请重启终端, 或执行：

source ~/.zshrc

• 配置 Codex

编辑 ~/.codex/config.toml：

vim ~/.codex/config.toml

在 config.toml 中加入或修改以下配置：

model_provider = "vtrix"
model = "gpt-5.5"
model_reasoning_effort = "medium"
preferred_auth_method = "apikey"

[model_providers.vtrix]
name = "vtrix"
base_url = "https://cloud.vtrix.ai/llm/openai/v1"
env_key = "VTRIX_API_KEY"
wire_api = "responses"

其中：

  • model = "gpt-5.5" 表示 Codex 默认使用的模型
  • model_reasoning_effort = "medium" 表示默认推理强度, 可按需改为 low, high 或 xhigh
  • base_url = "https://cloud.vtrix.ai/llm/openai/v1" 是 OpenAI Responses 兼容入口
  • env_key = "VTRIX_API_KEY" 表示从同名环境变量读取 API Key
提示

env_key 填的是环境变量名, 真实 API Key 请配置到对应环境变量中.

3

切换模型

如需切换模型, 只修改 model 的值即可.

类型推荐模型说明
智能体编程gpt-5.3-codex面向 Codex / 编程智能体任务优化
高性能gpt-5.5推理能力强, 适合复杂开发任务
标准gpt-5.4日常开发, 均衡
提示

在 模型页面 查看全部模型、能力与价格. 请优先选择支持工具调用和长上下文的模型.

4

启动会话

导航到你的项目目录并启动 Codex：

cd /path/to/your/project
codex

配置生效后, Codex 的请求将通过 Vtrix 路由.

• 校验配置

可先执行一个简单任务确认连接是否正常：

codex "请用一句话介绍当前项目"

如果 Codex 能正常回复, 说明模型与 API Key 已生效.

也可在 Vtrix 账户的 设置 中查看账单或用量, 确认请求是否到达.

故障排查

报错：401 Unauthorized

原因： API Key 未设置、设置错误, 或当前终端未加载环境变量.

处理：

echo $VTRIX_API_KEY

确认能输出你的 API Key. 如果为空, 请检查 ~/.zshrc 或 ~/.bashrc, 然后重新打开终端.

报错：404 Not Found 或 model not found

原因： model 填写错误, 或当前模型 ID 不存在.

处理： 前往 模型页面 复制正确的模型 ID, 然后更新 ~/.codex/config.toml.

报错：Connection error 或请求超时

原因： 当前任务过大、网络连接不稳定, 或模型响应时间过长.

处理： 将任务拆成更小的步骤, 例如：

请先阅读项目结构, 不要修改文件. 总结后等我确认.

或：

请每次只修改一个文件, 修改前先说明计划.
Codex 没有读取到新的配置

原因： Codex 会话启动时读取配置, 修改 config.toml 或环境变量后, 当前会话可能不会自动刷新.

处理： 完全退出 Codex, 重新打开终端后再启动：

codex
其他配置问题
  • 确认 ~/.codex/config.toml 中的 model_provider 与 [model_providers.vtrix] 名称一致
  • 确认 base_url 为 https://cloud.vtrix.ai/llm/openai/v1
  • 确认 env_key 对应的环境变量已设置
  • 确认 API Key 可用
  • 确认账户额度：查看余额
  • 确认所选模型适合 Codex 使用, 建议选择支持工具调用的模型

如需更多帮助, 可查阅本站其余文档或联系 Vtrix 支持.