企业官网建设流程全解析

OmniRoute CLI 集成指南：用 setup-* 命令与 omniroute run 把任意编码 CLI 接入统一 AI 网关

【免费下载链接】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 的 CLI 集成实战指南。OmniRoute 提供一套setup-*命令族，能够将 Codex、Claude Code、OpenCode、Cline、Kilo、Aider、Goose、Qwen 等主流编码 CLI 一键配置为以 OmniRoute 作为唯一后端，使工具只对接一个端点，由 OmniRoute 完成到各供应商的路由与自动故障转移；另有通用启动器omniroute run <target>，可在不写入任何配置的前提下以正确环境变量直接拉起目标 CLI。读完本文，你将掌握每条setup-*命令写入的文件、关键 flag 语义、本地与远程两种使用模式、不同工具对/v1路径的约定差异，以及如何用--dry-run、退出码与 CI 冒烟测试验证集成是否真正生效。

设计理念：一个端点 + 实时模型目录

所有setup-*命令共享同一条工作流：

1. 从正在运行的 OmniRoute（本地http://localhost:20128或通过--remote指定的远程实例）读取实时模型目录；
2. 在你的本机上写入目标工具自己的配置文件（例如 Codex 的~/.codex/*.config.toml、Claude Code 的~/.claude/profiles/*/settings.json）；
3. 只要工具支持，API Key 一律通过环境变量引用（如 OpenCode 的{env:OMNIROUTE_API_KEY}），避免把密钥明文落盘。

这样，模型目录在 OmniRoute 侧的任何变化（新供应商、新模型、配额降级）都无需手工同步到每个 CLI 的配置里，重新执行一次 setup 命令即可刷新。

除了面向配置的命令，OmniRoute 还提供通用启动器omniroute run <target>，直接以注入好的环境变量启动claude、codex、aider、goose、opencode、qwen或gemini，完全不写任何配置。目标及其别名来自规范清单 bin/cli/cli-manifest.mjs（例如claude-code|cc|anthropic、codex-cli|openai-codex|openai、goose-cli、open-code、qwen-code、gemini-cli），omniroute completion提供的补全候选词也由同一清单派生，保证"声明一次、处处一致"。曾经的按工具启动器omniroute launch（Claude Code）与omniroute launch-codex（Codex）仍保留可用。

从源码结构看，bin/cli/cli-manifest.mjs 中每个目标都带run、configure能力标记与runModel注入规范，而run.mjs、configure.mjs、completion.mjs都从这份清单派生目标列表，而不是各自维护一份私有副本；配套的漂移测试tests/unit/cli/cli-manifest-drift.test.ts用于断言清单与各消费面保持一致。

供应商接入：API 优先的 providers 命令族

在同一本地/远程上下文中，可以用一组 API 优先的命令接入供应商。它们把管理认证与供应商凭据分离，且结构化输出中从不打印凭据本身：

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（凭据来自 stdin 或环境变量，不会出现在命令行参数里）；--credential仅为受控的本地交互场景保留。providers remove在非交互终端上必须带--yes。五条命令都会遵守当前激活上下文，或全局的--base-url/--api-key选项。

主表：每条 setup-* 命令写什么、有哪些 flag

所有命令都优先遵循激活上下文（由omniroute connect设置，见 远程模式），或显式的--remote <url> --api-key <key>。表下"本地 vs 远程"的含义是：不带 flag 时默认指向http://localhost:20128；带--remote（或处于激活的远程上下文）时，从该服务器拉取目录，但仍把配置写在本机。

关键 flag 语义（已由命令源码验证）

• --remote <url>：从远程 OmniRoute 拉取目录（覆盖--port与激活上下文）。--api-key <key>为该服务器提供凭据（默认取OMNIROUTE_API_KEY环境变量或激活上下文的令牌）。
• --only <patterns>：逗号分隔的子串，只保留匹配的模型 ID（例如--only glm,kimi）。可用于setup-codex、setup-claude、setup-opencode、setup-continue、setup-cursor、setup-crush。
• --dry-run：精确打印将要写入的内容而不触碰文件系统。每条setup-*命令都支持，唯独setup-cursor除外（它本就不写文件）。
• --model <id>：对没有模型自动发现的工具是必需的（或交互式选择）：Cline、Kilo、Roo、Goose、Qwen、Aider、5dive。这些工具还接受--yes做非交互运行（此时必须给--model）。setup-opencode的--model用于设置顶层默认模型。
• --port <port>：本地 OmniRoute 端口（默认20128，设置--remote时忽略）。所有setup-*与两个启动器都有此 flag。

omniroute run的模型参数注入规则

omniroute run --model <id>遵循清单中每个目标的注入规范（见 bin/cli/cli-manifest.mjs 的manifestModelArgs）：

• aider收到--model openai/<id>（由runModel.prefix中的openai/决定）；
• opencode收到--model omniroute/<id>（仅当 ID 本身尚未携带该前缀时才加）；
• qwen与gemini原样接收 ID（prefix: ""）；
• claude通过ANTHROPIC_MODEL环境变量注入；
• goose通过GOOSE_MODEL注入；
• codex通过-c model_providers.omniroute.*参数注入。

Qwen 是唯一硬性要求--model的 run 目标——omniroute run qwen不带--model会以退出码2结束并给出明确错误（清单中qwen的runModel.required: true对应此行为，见 bin/cli/cli-manifest.mjs）。

omniroute run的退出码约定

• 子进程 CLI 自身的退出码原样透传；
• 2= 非法参数（不支持的目标、缺少必需的--model、容器守卫拦截）；
• 127= 目标二进制不在PATH中；
• 130/143/129= 启动被SIGINT/SIGTERM/SIGHUP终止；
• 1= 其他运行时启动失败。

launch与launch-codex两个启动器接受--profile <name>来选择由setup-claude/setup-codex写好的 profile，并把其余参数透传给底层claude/codex二进制。

交互式配置：omniroute configure

交互选择器同样服务于 setup 配方：

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

configure目前为codex、claude、opencode、qwen、aider、goose、cline、continue、kilo、5dive委托给经过测试的配方。仅面向 IDE、MITM 和纯指南的目录条目仍走显式的setup-*/手工流程，不作为可启动目标呈现。

注意：setup-opencode与omniroute setup opencode不是一回事

setup-opencode是 OpenCode 的轻量 openai 兼容集成；而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 包。两个包的仓库源码分别位于 @omniroute/opencode-plugin 与 @omniroute/opencode-plugin-v2。

本地使用：OmniRoute 跑在 localhost

在localhost:20128上运行 OmniRoute 后，直接为你的工具执行 setup 命令，目录从本地服务器拉取：

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

完全不写配置地启动（仅注入环境变量）：

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"

--之后的全部内容会原样传给底层 CLI，因此你可以对任意目标附加其专属参数。

从源码实现看，配置生成器集中在 src/lib/cli-helper/config-generator/，包含claude.ts、codex.ts、opencode.ts、cline.ts、continue.ts、kilocode.ts等。以 opencode.ts 为例，拉取目录前会经过assertSafeCatalogUrl的 SSRF 防护：循环回环/私网地址是合法的默认目录来源，但云元数据/链路本地跳板（如169.254.169.254、metadata.google.internal）一律被无条件拦截，同时拒绝非 http(s) 协议与内嵌凭据。

远程使用：笔记本驱动 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 # 铸造作用域令牌并保存上下文 omniroute setup-codex # ← 现在使用远程目录 omniroute setup-opencode # ← 同理 omniroute launch # ← Claude Code 指向远程

上下文、作用域与令牌管理的完整说明见 远程模式。

5dive：Agent 机群（仅配置，不可 run）

英文母版文档中还记录了 5dive 支持：5dive 运行一组长驻编码 Agent，每个 Agent 是独立 Unix 用户下的一个 systemd 单元。它不是编码 CLI 本身，因此omniroute run没有可启动对象——5dive 是纯 configure 目标（清单中5dive.run: false，见 bin/cli/cli-manifest.mjs）：

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

两种形式都写入一个 5diveauth profile，绑定到该 profile 的每个claude席位随后都指向 OmniRoute。该目标有三个特殊性：

• 以 root 身份运行在机群主机上：5dive 的动词作用于本地 systemd 单元与 root 持有的状态目录，没有远程模式。配方在非 root 时通过sudo重新执行（--no-sudo关闭并用打印命令代替）。
• 端点必须是https://（回环除外）：Agent 的 API Key 随每次请求携带在该 URL 上，5dive 拒绝明文离机端点，私网 LAN 地址也不例外。
• 每个席位的模型锁定优先于 profile：profile 携带ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL，但若某个席位仍锁定在默认模型 ID，首轮就会以"There's an issue with the selected model"失败。用可重复的--agent <name>一并锁定席位；配方会在未提供时打印对应命令。

API Key 通过stdin交给 5dive（--api-key=-），因此不会出现在ps输出中。将 profile 指向 OmniRoute组合（combo）而非单一模型，即可让机群获得供应商故障转移能力。

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

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

这些差异由命令源码统一处理，用户无需记忆——但理解它能帮你排查"为什么这个工具指向根路径、那个指向/v1"的问题，也能避免在手工配置时写错端点。

更新时保住原生依赖：--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 驱动与系统密钥环绑定会被悄悄移除）。先预览确切的命令再应用：

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

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

Google Gemini CLI：omniroute run gemini

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 基址（根路径，无/v1）；
• GEMINI_API_KEY→ 解析后的 OmniRoute 凭据（选项/环境变量/上下文）；
• 临时隔离的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目标对各自的冲突变量也做同样处理；
• 从--provider/--model注入--model <id>。

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

Gemini 的工作区信任保护在无头模式下仍然生效——请自行传--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）。例如 run-command.test.ts 断言resolveRunTarget能解析全部别名（cc→claude、openai→codex等），同文件 L66-L77 验证 aider 的--model openai/...前缀注入与根路径端点处理。

要针对真实的 OmniRoute 服务器验证真实的二进制，可使用位于 tests/integration/upstream-cli-smoke.int.test.ts 的可选工具。它从不自动运行（每个子测试在未设RUN_CLI_SMOKE=1时跳过），按环境变量名（而非值）传递凭据、从任何记录输出中打码形似密钥的字符串、跳过二进制未安装的目标，并把失败归类为认证/上游/配置三类，而非简单的布尔值：

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]基础配置
• 远程模式 —— 上下文、作用域访问令牌、驱动远程服务器
• VS Code Copilot Chat —— OmniCopilot 扩展；它也可以在编辑器内替你执行这些setup-*命令
• 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