Codex 接入
适用于 VS Code 的 OpenAI Codex 扩展（openai.chatgpt）、Codex CLI，以及使用相同配置的客户端。先在主站创建 API 密钥，确认余额和密钥分组可调用的模型；模型 ID 以模型广场为准。
VS Code：从齿轮进入配置
- 安装 OpenAI Codex 扩展。
- 打开 Codex 侧边栏 → 齿轮 → Codex Settings → 打开自定义 config.toml（Open config.toml）。
- 先备份打开的配置文件，再修改对应项；不要覆盖无关配置或重复添加同名 TOML 表。
供应商配置写在 Codex 的 config.toml，不是 VS Code 的 settings.json。通过扩展入口打开实际使用的文件，尤其适用于 Remote SSH，避免改错本地或远端配置。
方式一：直接填写 API Key
不想处理环境变量时，可以使用以下配置。将模型和密钥占位内容换成自己的值：
model = "REPLACE_WITH_MODEL_ID"
model_provider = "nekocloud"
[model_providers.nekocloud]
name = "猫云 API"
base_url = "https://api.nekocloud.vip/v1"
wire_api = "responses"
experimental_bearer_token = "REPLACE_WITH_API_KEY"experimental_bearer_token填 Key 本身，不要加Bearer前缀。- 在该供应商段移除
env_key和requires_openai_auth，不要混用不同认证方式。 model和model_provider是顶层字段，要放在各个[表名]之前；供应商 ID 要与表名一致。base_url不要填完整的/v1/responses；客户端会拼接端点。- 这里使用 Responses API，仅支持 Chat Completions 的接口不能直接照搬。
明文密钥
这种方式会把 Key 明文存到配置文件。不要提交到 Git、同步到公开仓库或发送完整截图。Linux/macOS 可对实际配置文件执行 chmod 600 限制读取权限；默认路径示例为 chmod 600 ~/.codex/config.toml。修改前保留原配置备份，备份也应妥善保管。该字段为实验性配置，升级后若不兼容，请核对官方参考或使用环境变量方式。
保存后执行 VS Code 命令 Developer: Reload Window（先保存正在编辑的文件），再新建 Codex 对话测试。这条齿轮入口及直接填 Key 的方式已由站主在 Linux Remote SSH 场景确认可用；不同扩展版本的文字可能略有差异。
方式二：使用环境变量
保留前面的模型、地址和协议，把认证行替换为：
# 位于 [model_providers.nekocloud] 段内
# 删除 experimental_bearer_token，不要同时保留两种方式
env_key = "NEKOCLOUD_API_KEY"env_key 只填写环境变量名，不能直接填写实际 Key。 实际密钥设置在运行 Codex 的进程环境中。
Linux / macOS 终端启动
Bash 中可以隐藏输入，避免真实 Key 进入命令历史：
read -rsp 'API Key: ' NEKOCLOUD_API_KEY
printf '\n'
export NEKOCLOUD_API_KEY
codex本机 VS Code 则先完全退出所有 VS Code 进程，再从同一终端执行 code .。临时变量只影响该终端及其新启动的子进程。写入 .bashrc / .zshrc 可以供相应 Shell 加载，但从桌面图标启动的应用不保证读取这些文件；写入 Shell 文件同样属于明文存储。
Windows 本机
打开「编辑账户的环境变量」，在用户变量中添加 NEKOCLOUD_API_KEY，变量值填实际 Key。保存后完全退出 VS Code，再重新打开。WSL、Remote SSH、容器中的插件不能仅依赖 Windows 用户变量。
Remote SSH：配置究竟放在哪里？
例如 Linux 本机通过 VS Code Remote SSH 连接另一台 Linux：配置和环境变量跟随 Codex 的实际运行位置，不是跟随屏幕所在位置。
- 执行 Developer: Show Running Extensions，确认
openai.chatgpt是否运行在远程扩展宿主。 - 若运行在远端，使用远端 SSH 登录用户的配置和环境。远端另外安装的桌面版 VS Code 与当前 VS Code Server 会话无关。
- 优先通过 Codex 齿轮打开实际配置。使用方式一无需再设置环境变量。
- 若用方式二，远端集成终端能读到变量，不代表已经运行的 Codex 进程也读到了。只运行
export、source ~/.bashrc或新开终端，不会改变父进程环境。
远端 Bash 的 .bashrc 若有非交互 Shell 提前 return，供启动流程使用的变量声明必须在该判断之前；实际是否加载仍取决于远程启动方式。仅在确认环境继承问题后，再保存工作、结束需要保留的终端任务，执行 Remote-SSH: Kill VS Code Server on Host... 并重连，使服务重新启动时读取环境。这会断开该用户的远程 VS Code 会话，可能影响集成终端任务；不是重启 Linux 或 SSH 服务。不要把重启当作所有 401 的通用解法。
CLI、桌面端与 Codex++
CLI 默认配置位置：
- Linux / macOS：
~/.codex/config.toml - Windows：
%USERPROFILE%\.codex\config.toml
自定义 CODEX_HOME 或客户端管理的配置可能使用其他路径，以实际打开的文件为准。CLI 可采用上面的直接填 Key 或环境变量方式。
部分桌面端 / Codex++「纯 API」配置使用 auth.json：在正确配置目录的 auth.json 中保存 OPENAI_API_KEY，并在对应 provider 段设置 requires_openai_auth = true。采用此方式时移除 env_key 与 experimental_bearer_token，先备份已有登录文件，不要直接覆盖原 OAuth 登录信息。客户端管理供应商时，优先通过其界面编辑并重新保存，避免生成器覆盖手工修改。
旧客户端生成的供应商配置可能缺少显式认证字段。核对实际配置并查阅客户端发布说明，必要时升级到修复版本；不要仅因为 401 就删除登录文件或轮换 Key。
401 与其他错误排查
API_KEY_REQUIRED：服务端未识别到密钥
典型报错：
401 Unauthorized
API_KEY_REQUIRED
API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header这表示请求到达了服务端，但没有识别到可用的密钥字段，不等于密钥本身无效。按顺序检查：
- 齿轮打开的是当前生效配置吗？顶层
model_provider是否选中了正确供应商？ - 对应 provider 是否明确配置了一种认证方式？不要混用。
env_key是否误填了实际 Key？若是，应改回变量名，或改用experimental_bearer_token。- 使用环境变量时，Codex 进程而不只是终端，是否拿到了非空变量？
- 配置正确仍失败，再携带请求时间、模型、错误码和 request id 联系客服排查链路；不要发密钥、认证头或完整
auth.json。
其他错误
| 现象 | 检查方向 |
|---|---|
| 其他 401 / 密钥无效 | 核对具体错误码，再检查 Key 拼写、撤销状态和认证方式 |
| 404 | 检查 Base URL 和 Responses 路由，不要重复拼接 /responses |
| 模型不存在 / 无权限 | 核对完整模型 ID、API Key 分组和模型权限 |
| 429 | 降低频率或并发，结合返回信息和使用记录判断限流 |
验证是否接入成功
新建 Codex 对话，发送一条简短消息（正常调用可能产生费用）。确认回复成功，再到主站「使用记录」核对请求时间、模型和计费。只有终端打印“变量存在”或配置保存成功，都不算业务验证。
参考：官方 IDE 设置 · 官方配置参考 · VS Code Remote SSH
工具链验收
在隔离小项目中要求读取一个非敏感文件并总结，确认工具请求、结果回传及最终回答均成功。聊天成功不等于工具链、图片或长上下文全部通过。保留权限审批，测试可能收费。