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

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, RTKCaveman 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-*命令共享同一条工作流从正在运行的 OmniRoute本地http://localhost:20128或通过--remote指定的远程实例读取实时模型目录在你的本机上写入目标工具自己的配置文件例如 Codex 的~/.codex/*.config.toml、Claude Code 的~/.claude/profiles/*/settings.json只要工具支持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-cliomniroute completion提供的补全候选词也由同一清单派生保证声明一次、处处一致。曾经的按工具启动器omniroute launchClaude Code与omniroute launch-codexCodex仍保留可用。从源码结构看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或处于激活的远程上下文时从该服务器拉取目录但仍把配置写在本机。命令目标工具写入的内容关键 flagomniroute setup-codexOpenAI Codex CLI~/.codex/name.config.toml—— 每个兼容文本模型一个配置文件codex --profile name使用--remote--api-key--only--dry-run--port--codex-homeomniroute setup-claudeClaude Code~/.claude/profiles/name/settings.json—— 每个匹配模型一个配置文件CLAUDE_CONFIG_DIR--remote--api-key--only--dry-run--port--claude-homeomniroute setup-opencodeOpenCodeopenai 兼容~/.config/opencode/opencode.json—— 名为omniroute的 provider包含目录中全部模型opencode -m omniroute/model--remote--api-key--only--model--dry-run--portomniroute setup-clineCline~/.cline/data/{globalState,secrets}.jsonCLI 模式 打印 VS Code 扩展设置--remote--api-key--model--yes--dry-run--port--cline-diromniroute setup-kiloKilo Code~/.local/share/kilo/auth.jsonCLI 若存在 VS Codesettings.json则合并kilocode.*配置--remote--api-key--model--yes--dry-run--port--auth-path--vscode-settingsomniroute setup-continueContinue /cnCLI~/.continue/config.yaml——provider: openai模型Key 通过${{ secrets.OMNIROUTE_API_KEY }}引用--remote--api-key--only--dry-run--port--config-pathomniroute setup-cursorCursor不写文件 —— 只打印应用内操作步骤Cursor 配置是封闭的 SQLite--remote--api-key--only--portomniroute setup-rooRoo Code~/.omniroute/roo-settings.json导入文档 若存在 VS Codesettings.json则设置roo-cline.autoImportSettingsPath--remote--api-key--model--yes--dry-run--port--import-path--vscode-settingsomniroute setup-crushCrush~/.config/crush/crush.json——openai-compatproviderKey 通过$OMNIROUTE_API_KEY--remote--api-key--only--dry-run--port--config-pathomniroute setup-gooseGoose~/.config/goose/config.yamlGOOSE_PROVIDER/OPENAI_HOST/GOOSE_MODEL 打印环境变量配方--remote--api-key--model--yes--dry-run--port--config-pathomniroute setup-aiderAider~/.aider.conf.ymlopenai-api-basemodel: openai/id 打印环境变量配方--remote--api-key--model--yes--dry-run--port--config-pathomniroute setup-qwenQwen Code~/.qwen/settings.json—— V4 版modelProviders.openai数组 在~/.qwen/.env中写入OMNIROUTE_API_KEY--remote--api-key--model--yes--dry-run--port--config-path--env-pathomniroute setup-5dive5diveAgent 机群不写$HOME下内容 —— 通过5dive agent auth set写入 5diveauth 配置文件/var/lib/5dive/auth-profiles/name/仅 root、运行于机群主机--remote--api-key--model--auth-profile--agent--byo-provider--fivedive-bin--no-sudo--yes--dry-run--portomniroute run target运行时启动通用不写文件 —— 以正确环境与参数拉起claude/codex/aider/goose/opencode/qwen/geminiQwen 与 Gemini 使用临时隔离 home--remote--base-url--context--provider--model--api-key--api-key-env--dry-run--json--port--profile--tokenomniroute launchClaude Code不写文件 —— 注入ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN后拉起claude--remote--api-key--token--profile--portomniroute launch-codexOpenAI Codex CLI不写文件 —— 通过-cflag 注入omnirouteprovider 后拉起codex--remote--api-key--profile(-p)--port关键 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 的manifestModelArgsaider收到--model openai/id由runModel.prefix中的openai/决定opencode收到--model omniroute/id仅当 ID 本身尚未携带该前缀时才加qwen与gemini原样接收 IDprefix: 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 --yesconfigure目前为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 v1omniroute/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_KEYsk-... # 通过 {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 指向远程上下文、作用域与令牌管理的完整说明见 远程模式。5diveAgent 机群仅配置不可 run英文母版文档中还记录了 5dive 支持5dive 运行一组长驻编码 Agent每个 Agent 是独立 Unix 用户下的一个 systemd 单元。它不是编码 CLI 本身因此omniroute run没有可启动对象——5dive 是纯 configure 目标清单中5dive.run: false见 bin/cli/cli-manifest.mjsomniroute 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 地址也不例外。每个席位的模型锁定优先于 profileprofile 携带ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL但若某个席位仍锁定在默认模型 ID首轮就会以Theres an issue with the selected model失败。用可重复的--agent name一并锁定席位配方会在未提供时打印对应命令。API Key 通过stdin交给 5dive--api-key-因此不会出现在ps输出中。将 profile 指向 OmniRoute组合combo而非单一模型即可让机群获得供应商故障转移能力。Base URL 约定哪些工具需要/v1OmniRoute 在/v1暴露 OpenAI 兼容面、在根路径暴露 Anthropic 面、在/v1beta暴露原生 Gemini 面。每条集成都接到其工具期望的形式已在命令源码中验证集成写入的 Base URL带/v1setup-clineopenAiBaseUrl根路径否 —— Cline 自行追加/v1/chat/completionssetup-gooseOPENAI_HOST根路径否 —— Goose 自行追加路径setup-aiderOPENAI_API_BASE根路径否 —— LiteLLM 追加/v1/chat/completionssetup-kilo、setup-roo、setup-continue、setup-crush、setup-cursor带/v1是setup-claudeANTHROPIC_BASE_URL、launch根路径否 —— Claude Code 追加/v1/messagessetup-codex、launch-codexmodel_providers.omniroute.base_url带/v1是setup-qwenmodelProviders.openai[].baseUrl带/v1是run geminiGOOGLE_GEMINI_BASE_URL根路径否 —— SDK 追加/v1beta/models/…setup-5diveauth profile 中的ANTHROPIC_BASE_URL根路径否 —— Claude Code 追加/v1/messages这些差异由命令源码统一处理用户无需记忆——但理解它能帮你排查为什么这个工具指向根路径、那个指向/v1的问题也能避免在手工配置时写错端点。更新时保住原生依赖--includeoptional用omniroute update更新时确认后或带--applyOmniRoute 会把--includeoptional内建进安装命令npm install -g omniroutelatest --includeoptional这不是传给omniroute update的 flag——更新器始终自动应用它。它保证optionalDependenciesbetter-sqlite3、keytar、tls-client、LLMLingua SLM 栈在更新后存活即使你的 npm 配置设置了omitoptional否则原生 SQLite 驱动与系统密钥环绑定会被悄悄移除。先预览确切的命令再应用omniroute update --dry-run # [DRY RUN] 将执行: npm install -g omniroutelatest --includeoptionalomniroute update的其他 flag源码已验证--check过期则退出码 1、--apply不提示直接安装、--changelog、--no-backup、--yes。Google Gemini CLIomniroute run geminiGemini CLI 的启动契约已针对google/gemini-cli0.50.0 验证该 CLI 尊重GOOGLE_GEMINI_BASE_URL并向其发出POST /v1beta/models/model:generateContent以及:streamGenerateContent?altsse——恰好对应 OmniRoute 的原生 Gemini 面/v1beta。omniroute run gemini自动完成以下接线GOOGLE_GEMINI_BASE_URL→ 激活的 OmniRoute 基址根路径无/v1GEMINI_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_TYPEgemini-api-key作为兜底——其他run目标对各自的冲突变量也做同样处理从--provider/--model注入--model id。omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p helloGemini 的工作区信任保护在无头模式下仍然生效——请自行传--skip-trust或交互式信任该目录启动器故意不绕过它。此启动器与ACP 注册src/lib/acp/registry.tsgemini --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_SMOKE1时跳过按环境变量名而非值传递凭据、从任何记录输出中打码形似密钥的字符串、跳过二进制未安装的目标并把失败归类为认证/上游/配置三类而非简单的布尔值RUN_CLI_SMOKE1 \ OMNIROUTE_SMOKE_BASE_URLhttp://localhost:20128 \ OMNIROUTE_SMOKE_MODELprovider/model \ OMNIROUTE_SMOKE_API_KEY_ENVOMNIROUTE_API_KEY \ node --import tsx/esm --test tests/integration/upstream-cli-smoke.int.test.ts可选OMNIROUTE_SMOKE_TARGETScodex,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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考