OmniRoute CLI 集成完全指南：一条命令把 Codex、Claude Code、OpenCode 等编码 CLI 全部接到统一网关

导读

OmniRoute 提供了一整套 setup-* 命令族，用来把 Codex、Claude Code、OpenCode、Cline 等主流编码 CLI 一键配置为以 OmniRoute 作为后端——工具只面向一个端点，由 OmniRoute 负责按配额自动回退（auto-fallback）地路由到合适的上游 provider。本文以 docs/guides/CLI-INTEGRATIONS.md 为核心，结合仓库中 bin/cli/ 的命令实现与 tests/ 下的回归测试，逐条讲解 15 个配置/启动命令的用法、全部关键参数、本地与远程两种工作模式，并深入到 manifest 驱动的 omniroute run 启动器、Base URL 约定、--include=optional 更新保护、Gemini CLI 启动契约与可选的真实二进制冒烟测试。读完本文，你将掌握：如何用一条命令为任意编码 CLI 生成可用的配置、如何零配置地用 omniroute run <target> 拉起目标 CLI、以及如何在本地或远程（VPS/Tailnet）OmniRoute 场景下进行模型选择与故障转移。

说明：本文所述全部命令、参数与默认值均以当前仓库实现为准。仓库的 i18n 目录中并无 docs/i18n/in/ 这一语言分支，本指南对应的英文规范文档位于 docs/guides/CLI-INTEGRATIONS.md，另有 zh-CN 译文。

---

一、设计总览：一条命令，两种信息源，三个输出层

所有 setup-* 命令遵循同一套工作模型：

1. 从运行中的 OmniRoute（本地或远程）读取"实时"模型目录（live model catalog）；
2. 在你自己机器的工具配置文件中写入配置；
3. API Key 一律通过环境变量引用（工具支持的任何地方都如此），密钥本身不会落盘写入明文。

除此之外，还存在一个通用启动器 omniroute run <target>：它直接以正确的环境变量拉起 claude、codex、aider、goose、opencode、qwen 或 gemini，完全不写任何配置文件。

1.1 目标的规范来源：bin/cli/cli-manifest.mjs

run、configure、completion 三个命令面的目标列表、别名解析与模型参数注入，全部来自单一规范清单 bin/cli/cli-manifest.mjs（CLI_TARGET_MANIFEST），而不是各自维护一份私有拷贝——新增目标（或重命名别名）只需声明一次。该文件头注释同时说明：服务端运行时目录 src/shared/services/cliRuntime.ts 是二进制路径、配置路径与健康检查的"真相来源"，并有防漂移测试 tests/unit/cli/cli-manifest-drift.test.ts 断言两界与所有消费面保持同步。

从 manifest 可以看到每个目标的别名与能力（run 可启动、configure 可交互配置、runModel 定义模型注入方式）：

• claude（别名 claude-code/cc/anthropic）：模型经 ANTHROPIC_MODEL 环境变量注入；
• codex（别名 codex-cli/openai-codex/openai）：模型经 -c model_providers.omniroute.* 参数注入；
• aider：模型走 --model openai/<id>（前缀 openai/）；
• goose（别名 goose-cli）：经 GOOSE_MODEL 注入；
• opencode（别名 open-code）：走 --model omniroute/<id>（前缀 omniroute/）；
• qwen（别名 qwen-code）：--model 原样传入，且标记为 required（必填）；
• gemini（别名 gemini-cli）：--model 原样传入，仅支持 run，不支持 configure；
• cline、continue（别名 cn）、kilo、5dive（别名 fivedive）：run: false，仅 configure。

manifestModelArgs() 在追加前缀时做了防重复处理：仅当模型 id 尚未携带该前缀时才添加（见 bin/cli/cli-manifest.mjs 的 manifestModelArgs 实现），因此 --model openai/gpt-5.4 不会被改写成 openai/openai/gpt-5.4。

1.2 交互式配置：omniroute configure <target>

setup-* 之外，还共享一套交互式选择器：

# 从活动本地或远程模型目录中选择并配置目标。
omniroute configure claude
omniroute configure opencode --provider glm
omniroute configure qwen --model qwen/qwen3.8-max-preview --yes

configure 目前委托给经过测试的 recipes：codex、claude、opencode、qwen、aider、goose、cline、continue、kilo 和 5dive。仅 IDE、MITM 与纯指南类目录条目仍走显式 setup-*/手工流程，不会作为可启动目标呈现。实现位于 bin/cli/commands/configure.mjs。

---

二、Master table：15 个命令速查

每个命令都遵守活动上下文（由 omniroute connect 设置，详见 Remote Mode）或显式的 --remote <url> --api-key <key> 参数。"Local vs remote"的含义是：不带任何参数时目标为 http://localhost:20128；带 --remote（或处于活动远程上下文）时从该服务器拉取目录、在本地写配置。

命令	工具	写入内容	关键参数	本地/远程
omniroute setup-codex	OpenAI Codex CLI	~/.codex/<name>.config.toml — 每个兼容文本模型一个 profile（codex --profile <name>）	--remote --api-key --only --dry-run --port --codex-home	Both
omniroute setup-claude	Claude Code	~/.claude/profiles/<name>/settings.json — 每个匹配模型一个 profile（CLAUDE_CONFIG_DIR）	--remote --api-key --only --dry-run --port --claude-home	Both
omniroute setup-opencode	OpenCode（openai 兼容）	~/.config/opencode/opencode.json — omniroute provider 含全部目录模型（opencode -m omniroute/<model>）	--remote --api-key --only --model --dry-run --port	Both
omniroute setup-cline	Cline	~/.cline/data/{globalState,secrets}.json（CLI 模式）+ 打印 VS Code 扩展设置	--remote --api-key --model --yes --dry-run --port --cline-dir	Both
omniroute setup-kilo	Kilo Code	~/.local/share/kilo/auth.json（CLI）+ 若存在则合并 kilocode.* 进 VS Code settings.json	--remote --api-key --model --yes --dry-run --port --auth-path --vscode-settings	Both
omniroute setup-continue	Continue / cn CLI	~/.continue/config.yaml — provider: openai 模型，Key 经 ${{ secrets.OMNIROUTE_API_KEY }}	--remote --api-key --only --dry-run --port --config-path	Both
omniroute setup-cursor	Cursor	不写文件 — 打印应用内操作步骤（Cursor 配置是封闭的 SQLite）	--remote --api-key --only --port	Both
omniroute setup-roo	Roo Code	~/.omniroute/roo-settings.json（导入文档）+ 若存在 VS Code settings.json 则设置 roo-cline.autoImportSettingsPath	--remote --api-key --model --yes --dry-run --port --import-path --vscode-settings	Both
omniroute setup-crush	Crush	~/.config/crush/crush.json — openai-compat provider，Key 经 $OMNIROUTE_API_KEY	--remote --api-key --only --dry-run --port --config-path	Both
omniroute setup-goose	Goose	~/.config/goose/config.yaml（GOOSE_PROVIDER/OPENAI_HOST/GOOSE_MODEL）+ 打印环境变量配方	--remote --api-key --model --yes --dry-run --port --config-path	Both
omniroute setup-aider	Aider	~/.aider.conf.yml（openai-api-base + model: openai/<id>）+ 打印环境变量配方	--remote --api-key --model --yes --dry-run --port --config-path	Both
omniroute setup-qwen	Qwen Code	~/.qwen/settings.json — V4 modelProviders.openai 数组 + OMNIROUTE_API_KEY 写入 ~/.qwen/.env	--remote --api-key --model --yes --dry-run --port --config-path --env-path	Both
omniroute setup-5dive	5dive（agent 集群）	不写 $HOME 下任何文件 — 通过 5dive agent auth set 写 5dive auth profile（/var/lib/5dive/auth-profiles/<name>/）；仅 root、运行在集群宿主机	--remote --api-key --model --auth-profile --agent --byo-provider --fivedive-bin --no-sudo --yes --dry-run --port	Both
omniroute run <target>	运行时启动（通用）	不写文件 — 以正确 env 与参数拉起 claude/codex/aider/goose/opencode/qwen/gemini；Qwen 与 Gemini 使用临时隔离 home	--remote --base-url --context --provider --model --api-key --api-key-env --dry-run --json --port --profile --token	Both
omniroute launch	Claude Code	不写文件 — 注入 ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN 拉起 claude	--remote --api-key --token --profile --port	Both
omniroute launch-codex	OpenAI Codex CLI	不写文件 — 通过 -c 参数注入 omniroute provider 拉起 codex	--remote --api-key --profile（-p）--port	Both

命令源码分布在 bin/cli/commands/ 下（setup-*.mjs、run.mjs、launch.mjs、launch-codex.mjs、configure.mjs、completion.mjs、providers.mjs 等）。

2.1 参数细则（已在命令源码中核实）

• --remote <url>：从远程 OmniRoute 拉取目录（覆盖 --port 与活动上下文）。--api-key <key> 提供该服务器的凭据（默认取 OMNIROUTE_API_KEY 环境变量，或活动上下文的 token）。
• --only <patterns>：逗号分隔的子串；只保留模型 id 匹配的条目（如 --only glm,kimi）。仅适用于 setup-codex、setup-claude、setup-opencode、setup-continue、setup-cursor、setup-crush。
• --dry-run：只打印将要写入的内容，不触碰文件系统。适用于除 setup-cursor 之外的所有 setup-* 命令（cursor 本身不写文件）。
• --model <id>：对无模型自动发现能力的工具（Cline、Kilo、Roo、Goose、Qwen、Aider、5dive）为必填（或交互选择）。这些工具还接受 --yes 以支持非交互运行（此时必须带 --model）。setup-opencode 的 --model 用于设置默认顶层模型。
• --model <id> 在 omniroute run 上的行为由 manifest 的 per-target 接线决定（bin/cli/cli-manifest.mjs）：aider 收到 --model openai/<id>、opencode 收到 --model omniroute/<id>（仅当 id 未携带前缀时才追加）；qwen 与 gemini 原样收到 id；claude 经 ANTHROPIC_MODEL 获取、goose 经 GOOSE_MODEL、codex 经 -c model_providers.omniroute.* 参数。Qwen 是唯一硬性要求 --model 的 run 目标——不带 --model 执行 omniroute run qwen 会以退出码 2 退出并给出明确报错（见 bin/cli/commands/run.mjs 中 manifestRequiresModel(target) && !model 的守卫逻辑）。
• --port <port>：本地 OmniRoute 端口（默认 20128，设置 --remote 时忽略）。所有 setup-* 与两个 launcher 均支持。
• omniroute run 退出码：子 CLI 自身的退出码原样透传；2 = 非法参数（不支持的目标、缺少必填 --model、容器守卫）；127 = 目标二进制不在 PATH；130/143/129 表示启动被 SIGINT/SIGTERM/SIGHUP 终止；1 = 其他运行时启动失败。退出码约定与信号映射（{ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }）在 bin/cli/commands/run.mjs 中可见。
• 两个 launcher（launch、launch-codex）接受 --profile <name> 来选择由 setup-claude/setup-codex 写出的 profile，同时透传底层 claude/codex 二进制的其余参数。

2.2 setup-opencode 与插件 setup opencode 的区别（易踩坑）

setup-opencode 是轻量级 openai 兼容的 OpenCode 集成。另有一个更丰富的插件集成——omniroute setup opencode——它安装 @omniroute/opencode-plugin。这是两个不同的命令；上表记录的是 setup-opencode。

插件按 OpenCode 主版本提供两个包，因为两个加载器期望不同的入口点：@omniroute/opencode-plugin 面向 OpenCode v1，@omniroute/opencode-plugin-v2 面向 OpenCode v2。v2 包较新（0.1.0），且遵循仍在演进的主机契约，因此它读取 OpenCode 播种到目录草稿中的形状而非自行假设。安装方式是在 opencode.json 中添加 plugins 条目；omniroute setup opencode 仍安装 v1 包。选项与凭据查找顺序见包内 README（opencode-plugin/README.md、opencode-plugin-v2/README.md）。

从源码看，setup-opencode 复用了服务端配置生成器（config-generator/opencode.ts）做目录拉取与合并，随后用 jsonc-parser 做保留注释的原地修改：把 provider.omniroute.options.apiKey 改写为环境变量引用 {env:OMNIROUTE_API_KEY}（常量 ENV_KEY_REF，见 bin/cli/commands/setup-opencode.mjs），实现"密钥绝不落盘"。其 URL 解析优先级为：--remote → 活动上下文 → http://localhost:<port>（默认 20128），与文档主表一致。

---

三、本地使用：localhost 即插即用

当 OmniRoute 运行在 localhost:20128 上时，直接执行对应工具的 setup 命令即可，目录从本地服务器拉取：

# Codex: 为每个匹配模型写一个 profile 到 ~/.codex/
omniroute setup-codex
codex --profile glm52            # 使用生成的 profile

# Claude Code: 写 per-model profiles，然后启动其中一个
omniroute setup-claude
omniroute launch --profile glm52

# OpenCode: 写 openai 兼容 provider，含目录中全部模型
omniroute setup-opencode
export OMNIROUTE_API_KEY=sk-...  # 经 {env:OMNIROUTE_API_KEY} 引用，绝不落盘
opencode -m omniroute/glm/glm-5.2 "..."

# 无自动发现能力的工具需要显式模型:
omniroute setup-aider --model glm/glm-5.2
omniroute setup-qwen --model qwen/qwen3.8-max-preview

# 只预览、不写任何文件:
omniroute setup-continue --dry-run

3.1 零配置启动：omniroute run 与 launch

完全不写任何配置、仅做环境变量注入的启动方式：

omniroute launch                 # Claude Code → 本地 OmniRoute
omniroute launch-codex           # Codex CLI → 本地 OmniRoute
omniroute launch-codex --profile glm52
omniroute run claude --model openai/gpt-5.4
omniroute run codex --model openai/gpt-5.4 --dry-run --json
omniroute run aider --model glm/glm-5.2 -- --message "reply OK"
omniroute run goose --model glm/glm-5.2
omniroute run opencode --model glm/glm-5.2 -- run "reply OK"
omniroute run qwen --model glm/glm-5.2 -- -p "reply OK"
omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p "reply OK"

# 显式命令路径: 透传 `--` 之后的所有内容
omniroute run claude -- --print-system-prompt "review this diff"

实现细节（来自 bin/cli/commands/run.mjs）：

• --dry-run 时输出"启动计划"而不执行：buildRunPlan 会生成 target、baseUrl、command、args、auth 来源、shell 模式、model、config overlay、env 增删清单，并在 JSON 模式下结构化打印——解析出的密钥值一律被脱敏（writeDryRunOutput 只输出 auth.source 与 present 布尔，绝不输出密钥本体）。
• 每个通用目标都有环境清理逻辑（genericEnv）：aider 会删除继承的 OPENAI_API_KEY/OPENAI_API_BASE/OPENAI_BASE_URL；goose 额外删除所有 GOOSE_* 变量；opencode 删除 OPENCODE_CONFIG_CONTENT；qwen 删除 QWEN_HOME 与 OMNIROUTE_API_KEY；gemini 删除 GOOGLE_GEMINI_BASE_URL、GEMINI_API_KEY、GOOGLE_API_KEY、GEMINI_CLI_HOME、GEMINI_DEFAULT_AUTH_TYPE、GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_GENAI_USE_GCA。这样保证宿主的陈旧环境不会覆盖 OmniRoute 定向启动。
• Qwen 与 Gemini 使用临时隔离 home：run 在 os.tmpdir() 下创建 omniroute-qwen-run-*（写 settings.json，含 modelProviders.openai 数组与 OMNIROUTE_API_KEY envKey 引用）或 omniroute-gemini-run-*（写 .gemini/settings.json，强制 security.auth.selectedType: "gemini-api-key"），并把 QWEN_HOME/GEMINI_CLI_HOME 指向它，进程退出后 rmSync 清理——文件中不含持久凭据。
• 启动前还会做一次 3 秒超时的健康检查（GET <baseUrl>/api/monitoring/health），不可达时提示 Start it or check --remote 并以 1 退出。
• 密钥解析优先级（toAuthSource/resolveAuthTokenOption）：显式 --token/--api-key 选项 → --api-key-env <name> 指定的环境变量（仅接受合法标识符名）→ 活动上下文（--context 或 OMNIROUTE_CONTEXT）→ OMNIROUTE_API_KEY → ANTHROPIC_AUTH_TOKEN → none。

---

四、远程使用：把任意编码 CLI 指向 VPS/Tailnet 上的 OmniRoute

用 --remote + --api-key 把任何 setup 命令指向远程 OmniRoute。目录从远程拉取，配置写在你的本地机器上：

# OpenCode 对接远程 VPS，只保留 glm/kimi 模型
omniroute setup-opencode --remote http://192.168.0.15:20128 --api-key oma_live_xxx \
  --only glm,kimi
opencode -m omniroute/glm/glm-5.2 "..."   # 先 export OMNIROUTE_API_KEY

# 从远程目录生成 Codex profiles
omniroute setup-codex --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 直接让 CLI 直连远程
omniroute launch       --remote http://192.168.0.15:20128 --api-key oma_live_xxx
omniroute launch-codex --remote http://192.168.0.15:20128 --api-key oma_live_xxx

与其每次手传 --remote/--api-key，不如登录一次、让活动上下文自动提供它们：

omniroute connect 192.168.0.15        # 铸造一个 scoped token 并保存上下文
omniroute setup-codex                 # ← 现在使用远程目录
omniroute setup-opencode              # ← 同样
omniroute launch                      # ← Claude Code 对接远程

上下文、作用域与 token 管理的完整说明见 Remote Mode。connect 命令实现位于 bin/cli/commands/connect.mjs。

---

五、5dive agent 集群：只配置、不启动的特殊目标

5dive 运行一队常驻编码 agent，每个都是独立 Unix 用户下的一个 systemd 单元。它本身不是编码 CLI，因此 omniroute run 没有可启动的东西——5dive 是只配置目标：

omniroute configure 5dive --model failover-demo --yes
omniroute setup-5dive --model failover-demo --auth-profile omniroute --agent worker1

两种形式都写一个 5dive auth profile，绑定到该 profile 的每个 claude seat 随后都对接 OmniRoute。该目标有三点特殊性：

1. 它运行在集群宿主机上，且以 root 身份。5dive 的动词作用于本地 systemd 单元与 root 所有的状态目录，没有远程模式。recipe 在非 root 时会通过 sudo 重新执行（--no-sudo 关闭该行为并改为打印命令）。
2. 端点必须是 https://，除非是 loopback。agent 的 API key 每次请求都携带在该 URL 上，5dive 拒绝明文非本机端点——私有 LAN 地址也不例外。
3. 每个 seat 自己的模型 pin 优先于 profile。profile 携带 ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL，但 seat 若仍钉在出厂模型 id 上，首轮会以 "There's an issue with the selected model" 失败。可重复传入 --agent <name> 一并 pin 住 seat；不传时 recipe 会打印命令。

API key 通过 stdin 交给 5dive（--api-key=-），因此永远不会出现在 ps 输出中。

把 profile 指向 OmniRoute combo（而非单个模型）正是集群 provider 故障转移的关键：在 issue #11578 记录的一次运行中，主端点中途硬宕机，agent 在回退端点上完成了剩余步骤、全程未暴露故障。实现位于 bin/cli/commands/setup-5dive.mjs。

---

六、Base URL 约定：哪些工具想要 /v1

OmniRoute 在 /v1 暴露 OpenAI 面、在根路径暴露 Anthropic 面、在 /v1beta 暴露原生 Gemini 面。每个集成都被接到其工具所期望的形式（已在命令源码中核实）：

集成	写入的 Base URL	/v1？
setup-cline（openAiBaseUrl）	root	否 — Cline 自行追加 /v1/chat/completions
setup-goose（OPENAI_HOST）	root	否 — Goose 自行追加路径
setup-aider（OPENAI_API_BASE）	root	否 — LiteLLM 追加 /v1/chat/completions
setup-kilo、setup-roo、setup-continue、setup-crush、setup-cursor	带 /v1	是
setup-claude（ANTHROPIC_BASE_URL）、launch	root	否 — Claude Code 追加 /v1/messages
setup-codex、launch-codex（model_providers.omniroute.base_url）	带 /v1	是
setup-qwen（modelProviders.openai[].baseUrl）	带 /v1	是
run gemini（GOOGLE_GEMINI_BASE_URL）	root	否 — SDK 追加 /v1beta/models/…
setup-5dive（auth profile 中的 ANTHROPIC_BASE_URL）	root	否 — Claude Code 追加 /v1/messages

对应的通用 run 目标同样遵循这套约定：例如 genericEnv 对 opencode 写入 ensureV1BaseUrl(baseUrl)（把不带 /v1 的地址规范化为带 /v1），而对 aider/goose/gemini 写入的就是根地址。

---

七、更新时保留原生依赖：--include=optional

用 omniroute update 更新时（确认后，或直接 --apply），OmniRoute 会内建 --include=optional 执行安装：

npm install -g omniroute@latest --include=optional

注意：这不是传给 omniroute update 的标志——它是更新器始终应用的。它保证 optionalDependencies（better-sqlite3、keytar、tls-client、LLMLingua SLM 栈）在更新后存活，即使你的 npm 配置设置了 omit=optional——否则原生 SQLite 驱动与系统钥匙串绑定会被悄悄丢弃。要预览确切命令而不实际应用：

omniroute update --dry-run
# [DRY RUN] Would run: npm install -g omniroute@latest --include=optional

omniroute update 的其他参数（源码核实）：--check（过时则退出 1）、--apply（不提示直接安装）、--changelog、--no-backup、--yes。实现位于 bin/cli/commands/update.mjs。

---

八、Google Gemini CLI：omniroute run gemini 的启动契约

该契约针对 @google/gemini-cli 0.50.0 验证：CLI 遵循 GOOGLE_GEMINI_BASE_URL，并向它发起 POST /v1beta/models/<model>:generateContent（以及 :streamGenerateContent?alt=sse）——这正是 OmniRoute 的原生 Gemini 面（/v1beta）。omniroute run gemini 自动完成以下接线：

• GOOGLE_GEMINI_BASE_URL → 活动 OmniRoute base URL（根地址，不带 /v1）；
• GEMINI_API_KEY → 解析后的 OmniRoute 凭据（选项/env/上下文）；
• 临时隔离的 GEMINI_CLI_HOME，其 .gemini/settings.json 选择 gemini-api-key 认证，使已存储的 Google OAuth 会话（Code Assist）永远不会覆盖 OmniRoute 定向启动——退出后删除；
• env 卫生：子进程 env 被清除 GOOGLE_API_KEY、GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_GENAI_USE_GCA（它们会把认证重定向到 Vertex/Code Assist），并设置 GEMINI_DEFAULT_AUTH_TYPE=gemini-api-key 作为双保险——其他 run 目标对自己冲突的变量也有同样的处理；
• --model <id> 从 --provider/--model 注入。

omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p "hello"

Gemini 的工作区信任守卫在 headless 模式下仍然生效——需要你自己传 --skip-trust（或交互信任目录）；launcher 刻意不绕过它。此 launcher 与 ACP 注册（src/lib/acp/registry.ts，gemini --acp）不同，后者仍是 /dashboard/acp-agents 的 agent 协议集成。相关实现见 bin/cli/commands/run.mjs 的 buildGeminiSettings() 与 gemini 分支。

---

九、真实冒烟测试（opt-in）：用真二进制对真服务器验证

确定性的启动计划回归跑在 CI 中（tests/unit/cli/run-command.test.ts、tests/unit/cli/run-execution.test.ts）。要用真实二进制对真实 OmniRoute 服务器验证，存在一个 opt-in 测试台 tests/integration/upstream-cli-smoke.int.test.ts。它从不自动运行（除非设置 RUN_CLI_SMOKE=1，否则每个子测试都跳过）、按环境变量名（而非值）传递凭据、对任何记录输出中的密钥形字符串做脱敏、跳过未安装二进制的目标，并把失败分类为 auth / upstream / config 而非一个裸布尔：

RUN_CLI_SMOKE=1 \
OMNIROUTE_SMOKE_BASE_URL="http://localhost:20128" \
OMNIROUTE_SMOKE_MODEL="<provider/model>" \
OMNIROUTE_SMOKE_API_KEY_ENV="OMNIROUTE_API_KEY" \
node --import tsx/esm --test tests/integration/upstream-cli-smoke.int.test.ts

可选：OMNIROUTE_SMOKE_TARGETS="codex,opencode,qwen" 限制扫描范围；OMNIROUTE_SMOKE_TIMEOUT_MS 覆盖每目标 120s 超时。

---

十、Provider 接入：同一上下文下的 API-first 命令

Provider 的接入（onboarding）同样可用本地/远程上下文完成。下面的 API-first 命令把管理认证与 provider 凭据分离，且结构化输出中永不打印凭据：

omniroute providers add glm --credential-env GLM_API_KEY --name work
omniroute providers import ./providers.json --dry-run --json
omniroute providers auth openai
omniroute providers edit <connection-id> --default-model glm/glm-5.2
omniroute providers remove <connection-id> --yes

脚本场景优先用 --credential-stdin 或 --credential-env；--credential 仅为受控的本地使用保留。providers remove 在非交互终端上要求 --yes。五个命令都遵守活动上下文或全局 --base-url/--api-key 选项。实现位于 bin/cli/commands/providers.mjs 与 bin/cli/commands/provider-crud.mjs。

---

十一、深入阅读：两份最丰富集成的深度文档

一次性、手写的基础配置，见对应工具的深度指南：

• Claude Code configuration — 更深入的 Claude Code 指南（ANTHROPIC_BASE_URL 指向 OmniRoute、token 管理等）；
• Codex CLI configuration — 一次性 [model_providers.omniroute] 基础配置；
• Remote Mode — 上下文、scoped access token、驱动远程服务器；
• VS Code Copilot Chat — OmniCopilot 扩展；它也能在编辑器内为你执行这些 setup-* 命令；
• CLI Tools reference — 受支持工具与 dashboard 页面的完整目录；
• Setup Guide — 安装方式与首次运行引导。

十二、快速上手决策表

你的场景	推荐命令
本地 OmniRoute，想用 Claude Code	omniroute setup-claude → omniroute launch --profile <name>
本地 OmniRoute，想用 Codex	omniroute setup-codex → codex --profile <name>
想用 OpenCode 且希望轻量 openai 兼容	omniroute setup-opencode + export OMNIROUTE_API_KEY
想用 OpenCode 且要插件级能力	omniroute setup opencode（安装 @omniroute/opencode-plugin）
不想写任何配置	omniroute run <target> [--model <id>]
远程 VPS/Tailnet 上的 OmniRoute	omniroute connect <host> 一次，然后所有 setup-*/run 自动走远程
只预览、不落地	任意 setup-* 加 --dry-run，或 run 加 --dry-run --json
5dive 集群故障转移	omniroute setup-5dive --model <combo> --auth-profile omniroute [--agent <name>]

这套命令族的设计核心在于：配置生成读取实时目录、密钥经环境变量引用、本地与远程同一套命令面、无模型自动发现的工具显式指定 --model、run 目标由单一 manifest 驱动。配合 configure 交互选择器与 providers 的 API-first 接入，OmniRoute 把"把任意编码 CLI 接到统一网关"这件事压缩成了一条可审计、可预览、可远程化执行的命令。