OmniRoute 的这个教程只处理标题中的具体任务。远程部署应让 20128 只监听回环地址，再由 Caddy 提供 TLS；Codex 使用受限端点令牌，自动回退需要可观察而不能静默换模型。
下面所有操作都先放在测试仓库、测试账号或仅回环监听的服务中。命令中的域名、用户名、路径与密钥是占位符，执行前需要替换。
远程网关的实际数据路径
这一节解决的是“远程网关的实际数据路径”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 OmniRoute 而言，判断依据是：远程部署应让 20128 只监听回环地址，再由 Caddy 提供 TLS；Codex 使用受限端点令牌，自动回退需要可观察而不能静默换模型。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
VPS 上准备 Docker 与持久卷
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“VPS 上准备 Docker 与持久卷”有可重复结果。
让 OmniRoute 只监听 127.0.0.1
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 让 OmniRoute 只监听 127.0.0.1 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
第一次读取模型列表
围绕“第一次读取模型列表”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
Caddy 反向代理的最小配置
这一节解决的是“Caddy 反向代理的最小配置”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 OmniRoute 而言，判断依据是：远程部署应让 20128 只监听回环地址，再由 Caddy 提供 TLS；Codex 使用受限端点令牌，自动回退需要可观察而不能静默换模型。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
签发 HTTPS 后检查证书链
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“签发 HTTPS 后检查证书链”有可重复结果。
为 Codex 创建专用访问令牌
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 为 Codex 创建专用访问令牌 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
auto 路由和固定模型如何选择
围绕“auto 路由和固定模型如何选择”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
Provider 限流时观察回退
这一节解决的是“Provider 限流时观察回退”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 OmniRoute 而言，判断依据是：远程部署应让 20128 只监听回环地址，再由 Caddy 提供 TLS；Codex 使用受限端点令牌，自动回退需要可观察而不能静默换模型。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
压缩功能先离线评估
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“压缩功能先离线评估”有可重复结果。
备份 omniroute-data 而不是只备份镜像
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 备份 omniroute-data 而不是只备份镜像 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
故障时让 Codex 切回原端点
围绕“故障时让 Codex 切回原端点”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
从 Caddy 日志区分网关和上游错误
这一节解决的是“从 Caddy 日志区分网关和上游错误”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 OmniRoute 而言，判断依据是：远程部署应让 20128 只监听回环地址，再由 Caddy 提供 TLS；Codex 使用受限端点令牌，自动回退需要可观察而不能静默换模型。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
限制远程令牌可调用的模型
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“限制远程令牌可调用的模型”有可重复结果。
模拟主 Provider 失效
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 模拟主 Provider 失效 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
升级镜像时固定回滚标签
围绕“升级镜像时固定回滚标签”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
OmniRoute 常见问题
是否可以跳过测试环境，直接把 OmniRoute 用到正式项目？
不建议。至少先完成一次最小成功请求、一次故意失败和一次恢复演练。
OmniRoute 命令能运行但结果不对，先查哪里？
先查输入范围、实际生效的配置和上游响应，再查模型总结。进程正常不代表业务结果正确。
如何避免 OmniRoute 的密钥或令牌进入 Git？
使用系统环境变量、Secret 管理或项目外配置文件，并在提交前搜索 diff。发现泄露后必须轮换密钥。
升级 OmniRoute 时最容易漏掉什么？
最容易漏掉配置格式、默认监听地址、权限范围和缓存兼容性。升级前保存版本与验证样本。
OmniRoute 验收问题
完成后应能回答下面的问题：
- 使用的是哪个确切版本？
- 哪些目录、端口、账号和外部服务可被访问？
- 成功结果如何回到原始数据或 Git diff？
- 上游失败时会报错、重试还是切换？
- 密钥是否可能出现在日志或历史记录？
- 如何在十分钟内回到修改前状态？
如果其中任何一项无法回答，OmniRoute 仍处于试用状态，不应扩大权限或接入生产自动化。