企业官网建设流程全解析

OmniRoute CLI 集成指南：用一套setup-*命令把 Codex、Claude Code、OpenCode 等编码 CLI 全部接入统一网关

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 提供了一整套setup-*命令族，用来把各类编码 CLI（Codex、Claude Code、OpenCode、Cline、Continue、Roo、Aider、Goose、Qwen Code、Kilo、Crush 等）一键指向 OmniRoute 作为统一后端——CLI 只与一个端点对话，模型路由、自动回退（auto-fallback）全部交给网关处理。本指南将带你掌握omniroute setup-*、omniroute run <target>、omniroute launch、omniroute configure等命令的完整用法：如何从本地或远程实例拉取实时模型目录、如何按模型批量生成配置文件、如何零配置注入环境变量直接启动目标 CLI，以及底层源码是如何实现这些行为的。

本文以 docs/guides/CLI-INTEGRATIONS.md 为主体骨架，并结合仓库中 bin/cli 下的命令实现与 tests 中的测试用例进行源码级补充。

一、整体设计：一个端点，N 个 CLI，自动回退

CLI 集成体系的设计目标非常明确：

• 每个setup-*命令从正在运行的 OmniRoute（本地localhost或远程 VPS）读取实时模型目录（GET /v1/models）；
• 在你的机器上写出该工具自己的配置文件（~/.codex/*.config.toml、~/.claude/profiles/*/settings.json、~/.config/opencode/opencode.json等）；
• 只要工具支持环境变量引用，API Key 一律通过环境变量引用（例如 OpenCode 的{env:OMNIROUTE_API_KEY}），绝不把凭据明文写进磁盘；
• CLI 只连接一个端点，由 OmniRoute 在背后完成按模型选择供应商与自动回退。

除了配置类命令，还提供通用的零配置启动器omniroute run <target>：它不写任何配置文件，直接以注入好的环境变量启动claude、codex、aider、goose、opencode、qwen或gemini。此外还有两个保留的旧式启动器：omniroute launch（Claude Code）与omniroute launch-codex（Codex）。

1.1 目标清单的唯一事实来源：cli-manifest.mjs

run、configure、completion三个命令的目标列表、别名解析与模型参数装配，全部由同一个清单文件驱动，而不是各写一份私有副本。见 bin/cli/cli-manifest.mjs：

• claude（别名claude-code、cc、anthropic）
• codex（别名codex-cli、openai-codex、openai）
• aider（别名无）
• goose（别名goose-cli）
• opencode（别名open-code）
• qwen（别名qwen-code）
• gemini（别名gemini-cli）
• cline、continue（别名cn）、kilo（别名kilocode等）、5dive（别名fivedive等）——后四者为纯配置目标（run: false），不可被run启动

每个目标声明了三种能力语义：

• run：是否可通过omniroute run <target>启动；
• configure：是否受omniroute configure <target>交互式选择器支持；
• runModel：run注入--model的方式（null表示模型走环境变量或 provider 参数而非 CLI 标志）。

例如 run.mjs 中runModel的取值直接决定了不同工具的模型注入方式：aider得到--model openai/<id>，opencode得到--model omniroute/<id>（前缀仅在 id 未携带时才追加），qwen与gemini得到原样 id，claude走ANTHROPIC_MODEL环境变量，goose走GOOSE_MODEL，codex走-c model_providers.omniroute.*参数。清单中还标注了唯一硬性要求--model的目标是 Qwen——不带模型启动omniroute run qwen会以错误码2退出并给出明确报错（见 run.mjs 与manifestRequiresModel的实现）。

仓库里还有一份防漂移测试 tests/unit/cli/cli-manifest-drift.test.ts，用于断言清单与src/shared/services/cliRuntime.ts（二进制路径、配置路径、健康检查的服务器侧事实来源）以及所有消费方保持同步。

omniroute completion提供的补全词同样派生自这份清单，因此新增一个目标只需在清单中声明一次。

1.2 凭据安全：管理认证与供应商凭据分离

供应商接入（onboarding）也沿用同一套本地/远程上下文。下面这组 API-first 命令把管理认证与供应商凭据分离，并且绝不在结构化输出中打印任何凭据：

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；
• 这五个命令都尊重活动上下文（active context）或全局--base-url/--api-key选项。

run.mjs中的认证解析同样值得注意：toAuthSource()把凭据来源归为option（显式 flag）→env（--api-key-env指定的变量或OMNIROUTE_API_KEY）→context（活动上下文 token）→none，并在 dry-run 计划里只输出来源而不输出值（见 run.mjs）。

二、命令总表：每个工具写什么、支持哪些 flag

以下总表覆盖全部setup-*命令。每条命令都遵循同一约定：无 flag 时目标为http://localhost:20128；带--remote（或激活了远程上下文）时从该服务器拉取目录，但配置仍然写在本机。

命令实现位于 bin/cli/commands 下的setup-*.mjs、run.mjs、launch.mjs、launch-codex.mjs。

2.1 flag 说明（已在命令源码中核实）

• --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-*命令都可用。
• --model <id>——对没有模型自动发现机制的工具是必需的（或在交互模式下选择）：Cline、Kilo、Roo、Goose、Qwen、Aider、5dive。这些工具还接受--yes用于非交互执行（此时必须配合--model）。setup-opencode用--model设置顶层默认模型。
• --model <id>在omniroute run上遵循清单中按目标装配的规则（见 1.1 节）；Qwen 是唯一硬性要求--model的 run 目标。
• --port <port>——本地 OmniRoute 端口（默认20128，设置了--remote时忽略）。所有setup-*与两个启动器均支持。
• omniroute run退出码约定：子 CLI 自身的退出码原样透传；2= 参数非法（目标不受支持、缺少必需的--model、容器守护拒绝）；127= 目标二进制不在PATH；130/143/129= 启动被SIGINT/SIGTERM/SIGHUP终止；1= 其他运行时启动失败。这一逻辑实现在 run.mjs 的信号处理与退出码映射中。
• 两个启动器（launch、launch-codex）接受--profile <name>选择setup-claude/setup-codex写出的 profile，并把剩余参数透传给底层claude/codex二进制。

2.2setup-codex的源码剖析：模型分类与 profile 生成

以 setup-codex.mjs 为例看底层逻辑。命令流程为：

1. 以GET /v1/models拉取实时目录（10 秒超时），失败时给出可操作的提示（确认 OmniRoute 已运行、--remoteURL 正确、可能需要--api-key）；
2. 对每个模型调用categoriseModel()或回退逻辑fallbackCodexProfile()判定该模型是否应该生成 profile；
3. 逐模型生成~/.codex/<name>.config.toml（幂等，重复执行原地更新）。

categoriseModel()把模型分为四档并绑定不同的 reasoning effort：

• Thinking 模型（effort: "xhigh"，summary: true）：如glm/glm-5.2（profile 名glm52）、glm/glm-5.2-max、kmc/kimi-k2.7；
• Good 模型（effort: "high"）：如ollamacloud/deepseek-v4-pro；
• Simple 模型（无 effort）：如ollamacloud/gemma4:31b；
• Fast 模型（effort: "low"）：如ollamacloud/gemini-3-flash、glm/glm-5-turbo。

每个分类还携带上下文窗口ctx、自动压缩阈值compact（约 85% 上下文）与工具输出 token 上限toolLimit。isCodexCompatibleTextModel()会排除 image/video/audio/embedding/rerank/moderation 等非文本模型；profileNameFromModelId()把模型 ID 规范化为文件系统安全的 profile 名（超长 ID 用 36 进制短哈希截断）。生成的 TOML 形如：

# codex --profile glm52 # glm/glm-5.2 model = "glm/glm-5.2" model_provider = "omniroute" model_reasoning_effort = "xhigh" model_reasoning_summary = "detailed" model_context_window = 131072 model_auto_compact_token_limit = 112000 tool_output_token_limit = 32768

categoriseModel被导出，正是为了让setup-claude复用同一套 profile 名（glm52、kimi-k27……）实现跨 CLI 命名一致。

三、交互式配置：omniroute configure <target>

setup-*之外还有共享同一交互式选择器的配置入口：

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

configure当前委托给经过测试的 recipe：codex、claude、opencode、qwen、aider、goose、cline、continue、kilo、5dive。实现见 configure.mjs：

• 从活动上下文的GET /v1/models拉取目录——处于远程模式（omniroute connect ...）时，你选择的是远程服务器的实时模型，而 profile 写在本机；
• 支持--provider/--model跳过交互、--yes非交互执行、--favorite/--unfavorite记忆模型偏好、--dry-run预览；
• 对codex直接在~/.codex/写 TOML（并保留.bak备份）；对其他目标则委托给对应的setup-*recipe（SETUP_MODULES表驱动），选择器本身保持为只读编排层，不重复实现配置合并逻辑；
• 模型选择结果会通过recordModelPreference记录偏好，供后续选择排序使用。

注意：IDE-only、MITM 与仅指南类的目录条目仍保留为显式setup-*/ 手动流程，不作为可启动目标暴露。

3.1 关于setup-opencode与插件集成的区别

setup-opencode是 OpenCode 的轻量 openai 兼容集成（在~/.config/opencode/opencode.json写入omnirouteprovider，key 通过{env:OMNIROUTE_API_KEY}引用，见 setup-opencode.mjs）。

仓库中还有更丰富的插件集成——omniroute setup opencode，它安装@omniroute/opencode-plugin。这是两条不同的命令，上面的总表记录的是setup-opencode。插件分为两个包、按 OpenCode 大版本分发（两个 loader 期望不同的入口）：

• @omniroute/opencode-plugin：针对 OpenCode v1；
• @omniroute/opencode-plugin-v2：针对 OpenCode v2（新版本0.1.0，宿主契约仍在演进，因此它读取 OpenCode 预置到目录草稿中的形状，而非自行假设）。

安装方式是在opencode.json添加plugins条目；omniroute setup opencode目前仍安装 v1 包。两个包的详细选项与凭据查找顺序见各自 README（@omniroute/opencode-plugin、@omniroute/opencode-plugin-v2）。

四、本地使用：OmniRoute 跑在localhost:20128

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

# Codex：为每个匹配模型写入一个 profile 到 ~/.codex/ omniroute setup-codex codex --profile glm52 # 使用生成的 profile # Claude Code：写每模型 profile，然后启动其中一个 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

4.1 零配置启动：只注入环境变量，不写任何配置文件

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"

run的通用目标走genericEnv()（见 run.mjs），为每个目标注入特定环境变量：

• aider：OPENAI_API_BASE+OPENAI_API_KEY（并清除继承的OPENAI_API_KEY/OPENAI_API_BASE/OPENAI_BASE_URL冲突变量）；
• goose：GOOSE_PROVIDER=openai+OPENAI_HOST+OPENAI_API_KEY（模型走GOOSE_MODEL），同时清除所有GOOSE_*与 OPENAI 冲突变量；
• opencode：通过OPENCODE_CONFIG_CONTENT进程环境注入一个完整 provider 配置（@ai-sdk/openai-compatible+baseURL自动补/v1+{env:OMNIROUTE_API_KEY}），进程退出即消失；
• qwen：OMNIROUTE_API_KEY+ 一个临时QWEN_HOME（内含settings.json，配置modelProviders.openai与selectedType: "openai"，文件权限0600，退出后删除）；
• gemini：GOOGLE_GEMINI_BASE_URL+GEMINI_API_KEY+GEMINI_DEFAULT_AUTH_TYPE=gemini-api-key+ 临时隔离的GEMINI_CLI_HOME。

claude与codex目标则由launch.mjs/launch-codex.mjs的专用构建器处理（见下）。

五、远程使用：--remote+--api-key或活动上下文

把任意 setup 命令指向远程 OmniRoute，只需要--remote+--api-key。目录从远程拉取，配置写在本机：

# 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 # 铸造一个范围受限 token，保存上下文 omniroute setup-codex # ← 现在使用远程目录 omniroute setup-opencode # ← 同理 omniroute launch # ← Claude Code 对接远程

resolveLaunchTarget()（launch.mjs）的解析优先级是：显式 flag → 活动上下文（远程模式）→localhost:<port>；认证同理（显式 token/api-key → 上下文 token →ANTHROPIC_AUTH_TOKEN/OMNIROUTE_API_KEY）。上下文的域、作用域与 token 管理详见 远程模式。

六、5dive agent 舰队（纯配置目标）

5dive 运行着一组长期运行的编码 agent，每个 agent 是各自 Unix 用户下的一个 systemd unit。它不是编码 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 的claudeseat 都经由 OmniRoute 通信。这个目标有三点特殊性：

1. 运行在舰队宿主机上，且为 root。5dive 的动词作用于本地 systemd unit 与 root 所有的状态目录，没有远程模式。recipe 在非 root 时通过sudo重新执行（--no-sudo关闭该行为并改为打印命令）。
2. 端点必须是https://，回环地址除外。agent 的 API key 每次请求都挂在 URL 上，5dive 拒绝离盒明文端点，私有局域网地址也不例外。
3. 每个 seat 自己的模型固定（model pin）优先级高于 profile。profile 携带ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL，但若 seat 仍固定到库存模型 ID，其首轮就会以"There's an issue with the selected model"失败。此时可传--agent <name>（可重复）一并固定 seat；不传则 recipe 打印对应命令。

API key 通过stdin交给 5dive（--api-key=-），因此不会出现在ps输出中。把 profile 指向 OmniRoutecombo（而非单个模型）即可获得舰队级供应商故障转移：当主端点在某次运行中途彻底宕机时，agent 会在回退端点上完成剩余步骤而不会暴露故障。

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

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

代码层面，ensureV1BaseUrl()（run.mjs）只在 URL 尚未以/v1结尾时追加；而 Claude 目标在buildClaudeEnv()中会剥离/v1后缀（launch.mjs），因为 Claude Code 自己会追加/v1/messages。

八、升级时保留原生依赖：--include=optional

用omniroute update升级时（确认后，或带--apply），OmniRoute 会内置--include=optional执行安装：

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

这不是你传给omniroute update的 flag——它总是由更新器自动应用。它保证optionalDependencies（better-sqlite3、keytar、tls-client、LLMLingua SLM 栈）在升级后依然存在，即使你的 npm 配置了omit=optional——否则会静默丢掉原生 SQLite 驱动与 OS keyring 绑定。想预览确切的命令而不执行：

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

omniroute update的其他 flag（源码已核实）：--check（过期则退出 1）、--apply（不询问直接安装）、--changelog、--no-backup、--yes。

九、omniroute run gemini：Google Gemini CLI 直连指南

启动契约已针对@google/gemini-cli0.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 凭据（option/env/context）；
• 一个临时隔离的GEMINI_CLI_HOME，其中的.gemini/settings.json选择gemini-api-key认证，因此已保存的 Google OAuth 会话（Code Assist）永远不会覆盖本次由 OmniRoute 引导的启动——退出后删除；
• 环境清洁：子进程环境会被清除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 的 workspace-trust 守护在无头模式下依然生效——你需要自己传--skip-trust（或交互式信任目录），启动器刻意不绕过它。该启动器与ACP 注册（src/lib/acp/registry.ts，gemini --acp）是不同的路径，后者是为/dashboard/acp-agents保留的 agent 协议集成。

十、真实冒烟清扫（可选启用）

确定性启动计划回归测试跑在 CI 里：tests/unit/cli/run-command.test.ts 与 tests/unit/cli/run-execution.test.ts。

若要针对真实OmniRoute 服务器验证真实二进制，仓库提供了一个可选启用的测试装置 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覆盖每个目标默认的 120 秒超时。

参见

• Claude Code 配置——更深入的 Claude Code 指南
• Codex CLI 配置——一次性[model_providers.omniroute]基础配置
• 远程模式——上下文、范围受限访问 token、驱动远程服务器
• CLI 工具参考——受支持工具的完整目录与仪表盘页面
• 安装指南——安装方式与首次运行引导

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute