01
Codex 已可正常启动
先安装 Codex，并至少启动一次，让用户级配置目录完成初始化。Windows 通常位于 %USERPROFILE%\.codex。
返回 Loopal API
Codex × Loopal API
在 Codex 中使用 Loopal 模型
从准备凭证到验证请求，完整配置 Codex 通过 OpenAI Responses 协议连接 Loopal API。既可以使用独立 Profile，也可以设为默认模型提供方。
约 5 分钟OpenAI Responses无需 models.json
00 · Preflight
开始之前
先确认下面三项，可以避免把安装问题、模型兼容问题和鉴权问题混在一起排查。
02
准备 Loopal API Key
API Key 只放在环境变量中，不要写入 config.toml 或提交到代码仓库。
03
选择 Responses 模型
记录一个支持 OpenAI Responses 的 Loopal Model ID，示例使用 gpt-5.6-terra。
01
准备 API Key 与环境变量
打开系统设置，复制你的 Loopal API Key。请妥善保管，不要在截图、日志或代码仓库中暴露真实 Key。
获取 API KeyCodex 将从 LOOPAL_API_KEY 环境变量读取凭证。先在当前终端设置变量，完成第一次连接验证：
macOS / Linux
export LOOPAL_API_KEY="<your Loopal API Key>"Windows PowerShell
$env:LOOPAL_API_KEY="<your Loopal API Key>"上面的命令只对当前终端及其启动的子进程生效。长期使用时，请将变量配置到系统或 Shell 环境；通过桌面图标启动的客户端不一定能读取终端里临时 export 的变量。
02
选择一种配置方式
两种方式使用同一套 Provider 配置。第一次接入建议先用独立 Profile，验证无误后再决定是否设为默认。
推荐 · Codex CLI
方式 A：创建独立 Loopal Profile
把配置保存为单独的 Profile，不修改你现有的默认模型和 Provider，适合试用、并行使用多个服务或快速切换。
macOS / Linux
~/.codex/loopal.config.tomlWindows PowerShell
$HOME\.codex\loopal.config.tomlWindows 资源管理器
%USERPROFILE%\.codex\loopal.config.tomlTOML 配置内容
model = "gpt-5.6-terra"
model_provider = "loopal"
[model_providers.loopal]
name = "Loopal"
base_url = "https://model.loopal.app/v1"
env_key = "LOOPAL_API_KEY"
wire_api = "responses"使用 Loopal Profile 启动
codex --profile loopalProfile 需要通过 codex --profile loopal 显式启用；不带 --profile 启动时，Codex 仍使用原来的默认配置。
可选 · 用户级默认配置
方式 B：将 Loopal 设为默认 Provider
希望直接执行 codex 就使用 Loopal，或让读取同一用户级配置的本地 Codex 客户端统一生效时，编辑默认配置文件。
macOS / Linux
~/.codex/config.tomlWindows PowerShell
$HOME\.codex\config.tomlWindows 资源管理器
%USERPROFILE%\.codex\config.tomlTOML 配置内容
model = "gpt-5.6-terra"
model_provider = "loopal"
[model_providers.loopal]
name = "Loopal"
base_url = "https://model.loopal.app/v1"
env_key = "LOOPAL_API_KEY"
wire_api = "responses"使用默认配置启动
codex修改前请备份原文件。若已有 model、model_provider 或 [model_providers.loopal]，更新原值，不要重复声明同一个 TOML 字段或表。Provider 与鉴权字段放在用户级配置中，可让各项目共用同一套接入设置。
示例使用 gpt-5.6-terra。你可以替换成其他支持 OpenAI Responses 的 Loopal Model ID；Codex 会直接发送这个 Model ID，因此本教程不需要额外创建 models.json。
查看可用模型03
启动并完成第一次验证
不要只确认 Codex 能打开；还要完成一次真实对话，才能同时验证配置读取、鉴权、模型 ID 和 Responses 路由。
1
确认启动方式
独立 Profile 使用 codex --profile loopal；默认配置直接使用 codex。修改环境变量后，需要从能读取该变量的环境重新启动客户端。
2
确认当前模型
启动界面或模型选择区域应显示 gpt-5.6-terra，或你在配置中填写的 Loopal Model ID。
3
发送最小测试消息
发送一条无需工具、无需仓库上下文的短消息，先排除权限、项目配置和工具调用造成的干扰。
建议的首次测试消息
请只回复：Loopal Codex connected能收到模型回复，且没有出现鉴权或模型不可用提示，才表示这次接入已经完成。
04
切换、停用与恢复
接入不会锁定 Codex。根据你选择的方式，可以随时回到原来的 Provider。
独立 Profile
退出当前会话，下一次启动时不传 --profile loopal，即可继续使用原来的默认配置。
默认配置
恢复备份的用户级 config.toml，或将 model 与 model_provider 改回原值，然后完全重启 Codex。
API Key
不再使用时，从 Shell 或系统环境中移除 LOOPAL_API_KEY；如果 Key 曾暴露，请在 Loopal 中立即轮换。
配置字段说明
modelCodex 默认使用的 Loopal Model ID。
model_provider模型提供方 ID，对应 [model_providers.loopal]。
base_urlLoopal 模型 API 根地址。Codex 会在该地址后调用 Responses 接口。
env_key保存 API Key 的环境变量名，避免在配置文件中写入明文凭证。
wire_apiCodex 自定义 Provider 使用 Responses 协议，固定为 "responses"。
为什么这样配置
- ·使用 env_key，而不是在 TOML 中保存明文 bearer token，便于轮换凭证并降低误提交风险。
- ·不维护 models.json：只要填写 Loopal 可用的 Responses Model ID，Codex 就可以直接发起请求。
- ·Provider 与鉴权配置使用用户级文件，避免在每个项目里重复配置，也避免把凭证接入方式绑定到代码仓库。
- ·base_url 填写 https://model.loopal.app/v1，不要再手动追加 /responses。
常见问题排查
按现象从上到下检查。排查时不要把完整 API Key 粘贴到日志、截图或聊天中。
现象常见原因处理方式
现象
启动后仍显示原来的模型
常见原因
Profile 没有启用，或默认配置文件没有被当前客户端重新加载。
处理方式
确认启动命令包含 --profile loopal；若使用默认配置，确认 macOS/Linux 路径为 ~/.codex/config.toml，Windows 路径为 %USERPROFILE%\.codex\config.toml，并完全重启客户端。
现象
提示缺少凭证或鉴权失败
常见原因
启动 Codex 的进程读不到 LOOPAL_API_KEY，或 API Key 已失效。
处理方式
在同一终端重新设置变量并启动 Codex；GUI 客户端请配置系统级环境变量。仍失败时，在 Loopal 中重新生成 Key。
现象
模型不存在或不可用
常见原因
Model ID 拼写错误、模型未开放，或该模型不支持 OpenAI Responses。
处理方式
从 Loopal 模型目录复制完整 Model ID，并确认它标记为支持 OpenAI Responses。
现象
配置解析失败
常见原因
config.toml 中重复声明了 model、model_provider 或同名 Provider 表。
处理方式
合并重复配置并检查 TOML 引号与表名；不要把完整示例无条件追加到已有文件末尾。
现象
终端可用，但桌面端或 IDE 不可用
常见原因
终端临时 export 的变量没有传递给单独启动的 GUI 进程。
处理方式
把 LOOPAL_API_KEY 配置到 GUI 进程可读取的系统环境，重启对应客户端后再验证。