OmniRoute CLI 集成指南：用 setup-* 与 omniroute run 将任意编码 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-*配置命令与通用的omniroute run <target>运行时启动器展开，说明如何让 Codex、Claude Code、OpenCode、Cline、Aider、Goose、Qwen Code、Gemini CLI 等编码工具通过同一个OmniRoute 端点接入 350+ 提供商与上千个模型，并获得自动 fallback 与配额感知的路由能力。读完本文，你将掌握：本地与远程（VPS/Tailnet）两种模式下如何一键生成各工具自己的配置文件、如何用--only/--dry-run/--model等关键旗标精细控制生成结果、各工具对 Base URL 是否追加/v1的约定，以及如何在不写任何配置的前提下用omniroute run直接拉起目标 CLI。文中同时结合仓库源码（bin/cli/cli-manifest.mjs、bin/cli/commands/run.mjs）给出实现级证据。
一、总览：一条命令族，统一所有编码 CLI
OmniRoute 的 CLI 集成设计思想是"工具只认一个端点，路由交给 OmniRoute"。每条setup-*命令都会从正在运行的 OmniRoute 实例（本地或远程）实时读取模型目录，然后在你本机写出目标工具自己的配置文件；只要工具支持，API Key 一律通过环境变量引用，不落盘。另有通用启动器omniroute run <target>，完全不写配置，只注入正确的环境变量后拉起claude、codex、aider、goose、opencode、qwen或gemini等二进制。
1.1 目标与别名来自唯一 manifest
所有可启动目标、别名与--model接线方式都集中定义在 bin/cli/cli-manifest.mjs 的CLI_TARGET_MANIFEST中：
claude-code|cc|anthropic→ Claude Codecodex-cli|openai-codex|openai→ OpenAI Codex CLIgoose-cli→ Gooseopen-code→ OpenCodeqwen-code→ Qwen Codegemini-cli→ Google Gemini CLI
omniroute run、omniroute configure与omniroute completion都从这份 manifest 派生目标列表与别名解析，而不是各自维护一份拷贝（见 bin/cli/cli-manifest.mjs 头部注释）。历史上按工具单独提供的omniroute launch（Claude Code）与omniroute launch-codex（Codex）依然保留可用。
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，这五条命令都遵循当前激活上下文或全局--base-url/--api-key选项。
二、Master 表：每条命令写入什么、支持哪些旗标
每条命令都遵循激活上下文（由omniroute connect设置，见 Mode Jarak Jauh → docs/guides/REMOTE-MODE.md）或显式--remote <url> --api-key <key>旗标。不带旗标时目标为http://localhost:20128；带--remote（或激活了远程上下文）时，从该服务器拉取目录、本地写配置。
| 命令 | 工具 | 写入内容 | 关键旗标 | Local vs remote |
|---|---|---|---|---|
omniroute setup-codex | OpenAI Codex CLI | ~/.codex/<name>.config.toml——每个兼容文本模型一个 profile（codex --profile <name>） | --remote--api-key--only--dry-run--port--codex-home | 两者 |
omniroute setup-claude | Claude Code | ~/.claude/profiles/<name>/settings.json——每个匹配模型一个 profile（CLAUDE_CONFIG_DIR） | --remote--api-key--only--dry-run--port--claude-home | 两者 |
omniroute setup-opencode | OpenCode（openai 兼容） | ~/.config/opencode/opencode.json——包含目录中每个模型的omnirouteprovider（opencode -m omniroute/<model>） | --remote--api-key--only--model--dry-run--port | 两者 |
omniroute setup-cline | Cline | ~/.cline/data/{globalState,secrets}.json（CLI 模式）+ 打印 VS Code 扩展设置 | --remote--api-key--model--yes--dry-run--port--cline-dir | 两者 |
omniroute setup-kilo | Kilo Code | ~/.local/share/kilo/auth.json（CLI）+ 若存在 VS Codesettings.json则合并kilocode.* | --remote--api-key--model--yes--dry-run--port--auth-path--vscode-settings | 两者 |
omniroute setup-continue | Continue /cnCLI | ~/.continue/config.yaml——provider: openai模型，Key 经${{ secrets.OMNIROUTE_API_KEY }} | --remote--api-key--only--dry-run--port--config-path | 两者 |
omniroute setup-cursor | Cursor | 不写文件——打印应用内操作步骤（Cursor 配置是封闭的 SQLite） | --remote--api-key--only--port | 两者 |
omniroute setup-roo | Roo Code | ~/.omniroute/roo-settings.json（导入文档）+ 若存在 VS Codesettings.json则设置roo-cline.autoImportSettingsPath | --remote--api-key--model--yes--dry-run--port--import-path--vscode-settings | 两者 |
omniroute setup-crush | Crush | ~/.config/crush/crush.json——openai-compatprovider，Key 经$OMNIROUTE_API_KEY | --remote--api-key--only--dry-run--port--config-path | 两者 |
omniroute setup-goose | Goose | ~/.config/goose/config.yaml（GOOSE_PROVIDER/OPENAI_HOST/GOOSE_MODEL）+ 打印 env 配方 | --remote--api-key--model--yes--dry-run--port--config-path | 两者 |
omniroute setup-aider | Aider | ~/.aider.conf.yml（openai-api-base+model: openai/<id>）+ 打印 env 配方 | --remote--api-key--model--yes--dry-run--port--config-path | 两者 |
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 | 两者 |
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 | 两者 |
omniroute launch | Claude Code | 不写文件——注入ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN后拉起claude | --remote--api-key--token--profile--port | 两者 |
omniroute launch-codex | OpenAI Codex CLI | 不写文件——通过-c旗标注入omnirouteprovider 后拉起codex | --remote--api-key--profile（-p）--port | 两者 |
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-*都支持，唯独setup-cursor除外（它从不写文件）。--model <id>：对没有模型自动发现能力的工具（Cline、Kilo、Roo、Goose、Qwen、Aider）是必需参数（或交互选择）。这些工具还接受--yes用于非交互执行（此时必须提供--model）。setup-opencode用--model设置顶层默认模型。omniroute run上的--model遵循 manifest 的按目标接线（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 目标——不带它运行omniroute run qwen会以退出码2报显式错误。该"必须带模型"的判断由 manifest 中的runModel.required字段驱动，见 bin/cli/cli-manifest.mjs 的manifestRequiresModel。
- aider收到
--port <port>：本地 OmniRoute 端口（默认20128，设置--remote时忽略）。所有setup-*与两个 launch 启动器都有。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二进制。
2.2 交互式选择器omniroute configure
配置配方共享同一交互选择器，可从激活的本地/远程模型目录中选择并配置目标：
# 从本地或远程激活目录中选择并配置目标。 omniroute configure claude omniroute configure opencode --provider glm omniroute configure qwen --model qwen/qwen3.8-max-preview --yesconfigure目前委托给经过测试的codex、claude、opencode、qwen、aider、goose、cline、continue、kilo等配方。仅 IDE 类、MITM 类与纯指南类目录条目仍走显式的setup-*/手动流程，不会被呈现为可启动目标。
注意
setup-opencode与omniroute setup opencode是两条不同命令：前者是轻量级 openai 兼容集成；后者安装@omniroute/opencode-plugin插件。插件分两个包、按 OpenCode 大版本区分——@omniroute/opencode-plugin用于 OpenCode v1，@omniroute/opencode-plugin-v2（版本 0.1.0，较新）用于 OpenCode v2，后者读取 OpenCode 写入目录草稿的形状而非自行假设。两个包的实现均位于仓库 @omniroute/opencode-plugin 与 @omniroute/opencode-plugin-v2。
三、本地使用：一条命令打通
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-run3.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.mjs的实现印证了这套流程：目标解析走resolveManifestTarget(target, "run")，模型参数由manifestModelArgs按 manifest 生成，token 解析使用--api-key-env这类"按环境变量名取凭据"的方式（见 bin/cli/commands/run.mjs），从而保证 dry-run 计划里永远不会出现凭据值。
四、远程使用：让笔记本驱动 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 "..." # 先导出 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。
五、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 命令，就能据此正确拼装 Base URL，避免 404 或协议不匹配。
六、升级时保住原生依赖：--include=optional
用omniroute update（确认后，或加--apply）升级时，OmniRoute 会内置执行带--include=optional的安装：
npm install -g omniroute@latest --include=optional这不是传给omniroute update的旗标——它由 updater 恒定应用。它保证optionalDependencies（better-sqlite3、keytar、tls-client、LLMLingua SLM 栈）在升级后存活，即使你的 npm 配置有omit=optional——否则原生 SQLite 驱动与 OS 钥匙串绑定会被静默移除。只想预览不执行：
omniroute update --dry-run # [DRY RUN] 将执行: npm install -g omniroute@latest --include=optionalomniroute update的其他旗标（源码中已验证）：--check（过期时退出码 1）、--apply（不询问直接安装）、--changelog、--no-backup、--yes。
七、专项：omniroute run gemini对接 Google Gemini CLI
该契约已针对@google/gemini-cli0.50.0 验证：Gemini 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 会剥离
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 的 workspace 信任守卫在 headless 模式下依然生效——需要你自己传--skip-trust（或交互式信任目录）；启动器刻意不绕过它。注意此启动器与ACP 注册（src/lib/acp/registry.ts 中的gemini --acp）不同，后者是面向/dashboard/acp-agents的 agent 协议集成。
八、可选的真实冒烟测试（opt-in）
确定性的启动计划回归测试在 CI 中运行（tests/unit/cli/run-command.test.ts 与 tests/unit/cli/run-execution.test.ts）。要针对真实的 OmniRoute 服务器验证真实的 CLI 二进制，仓库提供了 opt-in 的 harness：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 秒超时。
九、延伸阅读
- docs/guides/CLAUDE-CODE-CONFIGURATION.md —— Claude Code 的深入配置指南
- docs/guides/CODEX-CLI-CONFIGURATION.md —— Codex CLI 一次性手写
[model_providers.omniroute]基础配置 - docs/guides/REMOTE-MODE.md —— 上下文、受限访问 token、驱动远程服务器
- docs/guides/VSCODE-COPILOT.md —— OmniCopilot 扩展，也可在编辑器内替你运行这些
setup-*命令 - docs/reference/CLI-TOOLS.md —— 受支持工具的完整目录与仪表盘页面
- docs/guides/SETUP_GUIDE.md —— 安装方法与首次运行 onboarding
想深入底层实现，可继续阅读 bin/cli/cli-manifest.mjs（目标/别名唯一来源）、bin/cli/commands/run.mjs（运行时启动与环境注入）以及bin/cli/commands/setup-*.mjs系列（各工具配置生成器）。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
