企业官网建设流程全解析

OmniRoute CLI 集成指南：用setup-*、run与launch让任意编码 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 集成命令家族：setup-*系列命令可以把 Codex、Claude Code、OpenCode、Cline 等主流编码 CLI 一键配置为以 OmniRoute 为后端，使工具只与一个端点通信，由 OmniRoute 负责路由到正确的上游 Provider 并自动故障切换；omniroute run <target>通用启动器则能在不写任何配置文件的情况下，以正确的环境变量注入方式直接拉起claude、codex、aider、goose、opencode、qwen、gemini等目标。读完本文，你将掌握全部setup-*命令的写入位置与关键 flag、run启动器的目标清单与退出码约定、本地/远程两种使用模式、/v1基础 URL 约定，以及如何用可选的真实冒烟测试验证整条链路。

本文基于仓库中的 docs/guides/CLI-INTEGRATIONS.md（对应多语言翻译版本见 docs/i18n/az/docs/guides/CLI-INTEGRATIONS.md），并对照bin/cli/下的命令源码与tests/中的测试用例进行了核实。

概览：一个端点，一次配置，自动回退

集成思路非常直接：每个setup-*命令都从一个正在运行的 OmniRoute（本地或远程）读取实时模型目录，然后把目标工具自己的配置文件写到你本机。API Key 只要工具支持，就一律通过环境变量引用，绝不明文落盘。

# 从本地或远程模型目录中挑选模型，然后配置目标工具 omniroute configure claude omniroute configure opencode --provider glm omniroute configure qwen --model qwen/qwen3.8-max-preview --yes

除setup-*之外，还有一个通用启动器omniroute run <target>，它只做环境注入、不写任何配置；而omniroute launch（Claude Code）与omniroute launch-codex（Codex）则是保留的按工具专用旧版启动器。

run的目标与别名全部来自仓库中的权威清单bin/cli/cli-manifest.mjs，例如claude-code|cc|anthropic、codex-cli|openai-codex|openai、goose-cli、open-code、qwen-code、gemini-cli；omniroute completion提供的补全词同样派生自这一份清单。清单中的每个目标还声明了能力（run/configure）以及runModel注入方式，例如 aider 的--model openai/<id>、opencode 的--model omniroute/<id>（仅当 id 本身未带前缀时补加）、qwen 与 gemini 原样透传、claude 走ANTHROPIC_MODEL、goose 走GOOSE_MODEL、codex 走-c model_providers.omniroute.*参数。

Provider 自助接入（API 优先）

同样的本地/远程上下文中还提供了 Provider 自助接入命令。它们把管理端认证与 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选项。

总览表：每条setup-*命令写入什么

每条命令都尊重活动上下文（通过omniroute connect设置，见 docs/guides/REMOTE-MODE.md）或显式的--remote <url> --api-key <key>参数。"本地 vs 远程"的含义是：无 flag 时默认指向http://localhost:20128；带--remote（或处于活动远程上下文）时，从该服务器拉取目录，但配置仍写到本机。

以上命令文件均位于 bin/cli/commands/ 目录下（如setup-codex.mjs、setup-claude.mjs、setup-opencode.mjs、setup-aider.mjs、setup-qwen.mjs、setup-5dive.mjs、launch.mjs、launch-codex.mjs、run.mjs等）。

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-*命令都支持，唯独setup-cursor例外（它本就不写文件）。
• --model <id>— 对没有模型自动发现的工具是必需的（或交互式选择）：Cline、Kilo、Roo、Goose、Qwen、Aider、5dive。这些工具还接受--yes以支持非交互运行（此时必须带--model）。setup-opencode用--model设置默认顶层模型。
• omniroute run上的--model <id>遵循清单中每个目标的接线方式（见 bin/cli/cli-manifest.mjs）：aider收到--model openai/<id>，opencode收到--model omniroute/<id>（仅当 id 未自带前缀时补加）；qwen与gemini原样接收；claude通过ANTHROPIC_MODEL、goose通过GOOSE_MODEL、codex通过-c model_providers.omniroute.*参数注入。Qwen 是唯一硬性要求--model的 run 目标—omniroute run qwen不带它会以2退出并给出明确报错。
• --port <port>— 本地 OmniRoute 端口（默认20128，设置了--remote时忽略）。所有setup-*和两个启动器都支持。
• 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二进制。

configure：共享的交互式选择器

omniroute configure <target>与各setup-*共享同一套交互式选择逻辑：从活动（本地或远程）模型目录中挑选，然后委托给对应的 setup 配方。目前configure为codex、claude、opencode、qwen、aider、goose、cline、continue、kilo、5dive提供经过测试的配方，其委派映射定义在 bin/cli/commands/configure.mjs 的SETUP_MODULES中。仅 IDE、MITM 与纯指南类目录条目仍保持显式的setup-*/手工流程，不作为可启动目标呈现。

关于setup-opencode与 OpenCode 插件的重要区分

setup-opencode是轻量的 openai 兼容OpenCode 集成。仓库还提供了更丰富的插件集成 —omniroute setup opencode— 它会安装@omniroute/opencode-plugin。它们是两个不同的命令，上表记录的是setup-opencode。

插件按 OpenCode 大版本拆成两个包，因为两个 loader 期望不同的入口点：@omniroute/opencode-plugin用于 OpenCode v1，@omniroute/opencode-plugin-v2用于 OpenCode v2（两个包源码分别见 @omniroute/opencode-plugin 与 @omniroute/opencode-plugin-v2）。v2 包较新（0.1.0），遵循仍在演进中的宿主契约，因此它读取 OpenCode 播种到目录草稿中的形状而不是臆测。安装方式是在opencode.json中添加plugins条目；omniroute setup opencode仍安装 v1 包。

本地使用：一条命令完成配置

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

# Codex：按匹配模型在 ~/.codex/ 下写 profile 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

以setup-codex为例，其源码（bin/cli/commands/setup-codex.mjs）会先通过GET /v1/models连接正在运行的 OmniRoute 实例（本地或远程 VPS）拉取实时目录，再为每个模型生成~/.codex/<name>.config.tomlprofile 文件 — 这样你就能用单个 flag（codex --profile glm52）切换 Provider，无需手改配置文件。命令是幂等的：重复运行会就地更新已有 profile。其内部的categoriseModel()函数把模型分为 thinking / good / simple 三类并映射为统一的 profile 命名（如glm52、kimi-k27、deepseek-pro），该函数被导出供setup-claude复用，以保证跨 CLI 的 profile 命名一致（glm52、kimi-k27…）。

完全不写配置的启动方式（仅环境注入）：

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"

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

关于上下文、作用域与 token 管理，详见 docs/guides/REMOTE-MODE.md。omniroute connect的实现位于 bin/cli/commands/connect.mjs。

5dive agent 机群（仅配置目标）

5dive 运行着一组常驻编码 agent，每个 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

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

• 它运行在机群主机上，以 root 身份执行。5dive 的操作作用于本地 systemd 单元与 root 所有的状态目录，没有远程模式。配方在非 root 时会通过sudo重新执行（--no-sudo关闭该行为并改为打印命令）。
• 端点必须是https://，除非是 loopback。agent 的 API key 每次请求都会携带在该 URL 上，5dive 拒绝明文离盒端点，私有局域网地址也不例外。
• 每个席位的模型 pin 优先级高于 profile。profile 携带ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL，但若某席位仍被 pin 到标准模型 id，首轮对话就会报"There's an issue with the selected model"。可重复传--agent <name>来同时 pin 席位；不传时配方会打印出相应命令。

API key 通过stdin（--api-key=-）交给 5dive，因此它绝不会出现在ps输出中。把 profile 指向 OmniRoutecombo而非单个模型，即可为机群带来 Provider 故障切换：当主端点在中途硬故障时，agent 会在后备端点上完成剩余步骤，用户完全感知不到中断。

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

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

更新时保住原生依赖：--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 钥匙串绑定）。不应用而先预览确切命令：

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目标对其各自的冲突变量也接受同样的处理；
• 从--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）。要用真实二进制对真实OmniRoute 服务器做验证，仓库提供了可选 harness：tests/integration/upstream-cli-smoke.int.test.ts。它从不自动运行（每个子测试在RUN_CLI_SMOKE != 1时跳过），凭据以环境变量名传递（绝不以值传递），会对记录输出中的 key 形态字符串做脱敏，跳过未安装对应二进制的目标，并把失败分类为 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 秒的默认超时。

进一步阅读

• docs/guides/CLAUDE-CODE-CONFIGURATION.md — 更深入的 Claude Code 指南（含ANTHROPIC_*环境变量表与/model选择器中的发现别名）
• docs/guides/CODEX-CLI-CONFIGURATION.md — 一次性[model_providers.omniroute]基础配置
• docs/guides/REMOTE-MODE.md — 上下文、受限访问 token、驱动远程服务器
• docs/reference/CLI-TOOLS.md — 受支持工具的完整目录 + 仪表盘页面
• docs/guides/SETUP_GUIDE.md — 安装方式与首次运行引导

【免费下载链接】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