OmniRoute CLI 集成指南用一条命令把 Codex、Claude Code、OpenCode、Cline 等全部编码 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导读OmniRoute 提供一整套setup-*配置命令和一个通用启动器omniroute run target用于将 Codex、Claude Code、OpenCode、Cline、Continue、Qwen Code、Aider、Goose、Gemini CLI 等主流编码 CLI 的 backend 指向 OmniRoute 的单一端点——工具只对话一个地址由 OmniRoute 负责把请求路由到正确的模型供应商并自动回退。读完本文你将掌握如何从本地或远程 OmniRoute 的实时模型目录生成各工具的原生配置文件profile、provider、settings.json、如何在不写任何配置文件的情况下用环境注入直接启动目标 CLI、以及--only/--dry-run/--model/--port等核心参数的语义与退出码约定。一、两条主路径setup-*写配置run零配置直启OmniRoute 面向 CLI 集成提供了两条互补的主路径核心命令族均见 docs/guides/CLI-INTEGRATIONS.mdomniroute setup-tool写配置读取正在运行的 OmniRoute本地localhost:20128或远端服务器的实时模型目录live model catalog然后在你本机写出该工具自己的配置文件。API Key 一律通过环境变量引用只要工具支持绝不落盘。omniroute run target零配置启动不写任何配置直接以正确注入的环境变量拉起claude、codex、aider、goose、opencode、qwen或gemini。目标是带别名的claude-code|cc|anthropic、codex-cli|openai-codex|openai、goose-cli、open-code、qwen-code、gemini-cliomniroute completion也提供同一套源自 manifest 的目标词补全。早期按工具分的启动器omniroute launchClaude Code与omniroute launch-codexCodex继续保留。所有目标及别名的唯一权威来源是 manifest 文件 bin/cli/cli-manifest.mjsrun.mjs、configure.mjs、completion.mjs都从这张表派生目标列表、别名解析与模型参数装配而不是各自维护私有副本——新增目标或重命名别名只需声明一次。这正是“单点事实来源single source of truth”的工程实践仓库中的防漂移测试 tests/unit/cli/cli-manifest-drift.test.ts 会断言 manifest、CLI 命令面与运行时目录三方保持一致。供应商 onboarding把上游凭据交给 OmniRoute供应商接入与 CLI 集成共享同一套本地/远程上下文。下面这些 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--credential仅保留给受控的本地使用。providers remove在非交互终端上必须带--yes。这五条命令都遵循**活动上下文active context**或全局选项--base-url/--api-key。二、主表每条setup-*命令写什么、支持哪些参数每条命令都遵循活动上下文用omniroute connect设置详见 docs/guides/REMOTE-MODE.md或显式的--remote url --api-key key。下表“本地 vs 远程”含义不带参数时目标为http://localhost:20128带--remote或存在远程活动上下文时从该服务器拉取目录并在本地写配置。命令目标工具写入内容关键参数本地/远程omniroute setup-codexOpenAI Codex CLI~/.codex/name.config.toml——每个兼容文本模型一个 profilecodex --profile name--remote--api-key--only--dry-run--port--codex-home两者omniroute setup-claudeClaude Code~/.claude/profiles/name/settings.json——每个匹配模型一个 profileCLAUDE_CONFIG_DIR--remote--api-key--only--dry-run--port--claude-home两者omniroute setup-opencodeOpenCodeopenai 兼容~/.config/opencode/opencode.json——omnirouteprovider 含目录中每个模型opencode -m omniroute/model--remote--api-key--only--model--dry-run--port两者omniroute setup-clineCline~/.cline/data/{globalState,secrets}.jsonCLI 模式 打印 VS Code 扩展设置--remote--api-key--model--yes--dry-run--port--cline-dir两者omniroute setup-kiloKilo Code~/.local/share/kilo/auth.jsonCLI 若存在 VS Codesettings.json则合并kilocode.*--remote--api-key--model--yes--dry-run--port--auth-path--vscode-settings两者omniroute setup-continueContinue /cnCLI~/.continue/config.yaml——provider: openai模型密钥经${{ secrets.OMNIROUTE_API_KEY }}--remote--api-key--only--dry-run--port--config-path两者omniroute setup-cursorCursor什么都不写——仅打印应用内操作步骤Cursor 配置是黑盒 SQLite--remote--api-key--only--port两者omniroute setup-rooRoo 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-crushCrush~/.config/crush/crush.json——openai-compatprovider密钥经$OMNIROUTE_API_KEY--remote--api-key--only--dry-run--port--config-path两者omniroute setup-gooseGoose~/.config/goose/config.yamlGOOSE_PROVIDER/OPENAI_HOST/GOOSE_MODEL 打印环境配方--remote--api-key--model--yes--dry-run--port--config-path两者omniroute setup-aiderAider~/.aider.conf.ymlopenai-api-basemodel: openai/id 打印环境配方--remote--api-key--model--yes--dry-run--port--config-path两者omniroute setup-qwenQwen 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运行时启动通用什么都不写——以正确环境与参数拉起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--token两者omniroute launchClaude Code什么都不写——注入ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN后拉起claude--remote--api-key--token--profile--port两者omniroute launch-codexOpenAI Codex CLI什么都不写——通过-c参数注入omnirouteprovider 后拉起codex--remote--api-key--profile-p--port两者注意区分setup-opencode是 OpenCode 的轻量 openai 兼容集成另有更丰富的插件集成omniroute setup opencode安装omniroute/opencode-plugin。两者是不同命令上表记录的是setup-opencode。插件按 OpenCode 主版本拆成两个包OpenCode v1 用omniroute/opencode-pluginOpenCode v2 用omniroute/opencode-plugin-v2两个包都在仓库omniroute/目录下插件说明见 omniroute/opencode-plugin/README.md 与 omniroute/opencode-plugin-v2/README.md。参数语义详解已在命令源码中核实--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设置顶层默认模型。--model id在omniroute run上的装配逻辑遵循 manifest 的按目标接线见 bin/cli/cli-manifest.mjs 的manifestModelArgs/manifestRequiresModelaider收到--model openai/idopencode收到--model omniroute/id仅当 ID 本身未带该前缀时才加qwen与gemini原样收到 IDclaude通过ANTHROPIC_MODEL环境变量注入goose通过GOOSE_MODELcodex通过-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二进制。交互式选择器omniroute configure target配置配方共享同一个交互式模型选择器# 从活动本地或远程模型目录中挑选并配置目标工具。 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配方对应实现位于 bin/cli/commands/configure.mjs。仅 IDE、MITM 与纯指南类的目录条目仍走显式setup-*/手动流程不会被当作可启动目标呈现。三、本地使用OmniRoute 跑在localhost:20128OmniRoute 在本地运行时直接对你的工具执行配置命令即可目录从本地服务器拉取# Codex按匹配模型在 ~/.codex/ 写 profile 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_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 hello # 显式命令路径-- 之后的内容全部透传 omniroute run claude -- --print-system-prompt review this diff这里的--model装配、退出码、目标解析均由 manifest 驱动启动后的进程管理、PATH 探测与健康检查则落到运行时服务 src/shared/services/cliRuntime.ts。该文件维护着每个工具的权威运行时条目默认命令、可覆盖的CLI_*_BIN环境变量、配置文件路径、健康检查超时并用CLI_TOOL_ALIASES如cc → claude、openai-codex → codex、cn → continue在边界处归一化旧别名。四、远程使用笔记本驱动 VPS / Tailnet 上的 OmniRoute用--remote--api-key把任何配置命令指向远端 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 # 铸造 scope 受限的 token 并存储上下文 omniroute setup-codex # ← 现在使用远端目录 omniroute setup-opencode # ← 同理 omniroute launch # ← Claude Code 直连远端上下文、scope 与 token 管理详见 docs/guides/REMOTE-MODE.md。五、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/…这段约定在 src/shared/constants/cliTools.ts 与各配置生成器如 src/lib/cli-helper/config-generator/claude.ts中落地仪表盘的健康检查与命令行写出的配置共用同一套路径认知。六、更新时保住原生依赖--includeoptional使用omniroute update确认后或带--apply更新时OmniRoute 内置执行带--includeoptional的安装命令npm install -g omniroutelatest --includeoptional这不是你传给omniroute update的参数——更新程序始终如此执行。它保证optionalDependenciesbetter-sqlite3、keytar、tls-client、LLMLingua SLM 栈在升级后仍然存在即使你的 npm 配置设了omitoptional否则原生 SQLite 驱动与系统钥匙串绑定会被悄悄丢弃。预览确切命令而不实际应用omniroute update --dry-run # [DRY RUN] Would run: npm install -g omniroutelatest --includeoptionalomniroute update的其他参数已在源码核实--check过时则退出码 1、--apply不询问直接安装、--changelog、--no-backup、--yes。七、omniroute run geminiGoogle Gemini CLI 的原生接线该启动契约已对照google/gemini-cli0.50.0 验证Gemini CLI 尊重GOOGLE_GEMINI_BASE_URL并向其发出POST /v1beta/models/model:generateContent以及:streamGenerateContent?altsse——恰好命中 OmniRoute 的原生 Gemini 面/v1beta。omniroute run gemini自动完成以下接线GOOGLE_GEMINI_BASE_URL→ 活动 OmniRoute 的 Base URL根路径不带/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.ts的gemini --acp是两回事后者是为/dashboard/acp-agents服务的智能体协议集成。八、真实二进制冒烟测试opt-in 框架CI 中有确定性的启动计划回归测试tests/unit/cli/run-command.test.ts、tests/unit/cli/run-execution.test.ts。要拿真实二进制打真实 OmniRoute 服务器存在一个 opt-in 测试框架 tests/integration/upstream-cli-smoke.int.test.ts。它从不自动运行除非RUN_CLI_SMOKE1否则每个子测试都跳过凭据以环境变量名传递绝不传值对任何记录输出中的形如密钥的字符串做脱敏自动跳过二进制未安装的目标并把失败分类为 auth / upstream / config而非简单的布尔值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覆盖每目标 120s 的超时。九、补充5dive 智能体舰队configure-only 目标本节源自该文档的英文规范版 docs/guides/CLI-INTEGRATIONS.md 及仓库实现 bin/cli/commands/setup-5dive.mjs配套测试 tests/unit/cli/setup-5dive.test.ts。5dive 运行着一支长驻编码智能体舰队每个智能体是以独立 Unix 用户运行的 systemd 单元。它本身不是编码 CLI所以omniroute run没有可启动的东西——5dive 是 configure-only 目标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://除非是 loopbackagent 的 API Key 随每个请求附在该 URL 上5dive 拒绝明文离机端点私有局域网地址也不例外。每个席位的模型 pin 优先于 profileprofile 携带ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL但若某席位仍 pin 在出厂模型 ID 上首轮对话会以 “Theres an issue with the selected model” 失败。传--agent name可重复可同时 pin 席位不传时配方会打印对应命令。API Key 通过stdin交给 5dive--api-key-因此不会出现在ps输出中。把 profile 指向 OmniRoutecombo而非单一模型就能让舰队获得供应商故障转移当主端点在某轮对话中途硬故障时agent 会在回退端点上完成剩余步骤而不暴露中断。相关文档docs/guides/CLAUDE-CODE-CONFIGURATION.md —— Claude Code 深度配置指南docs/guides/CODEX-CLI-CONFIGURATION.md —— 一次性手写[model_providers.omniroute]基础配置docs/guides/REMOTE-MODE.md —— 上下文、scope 受限访问 token、驱动远端服务器docs/reference/CLI-TOOLS.md —— 受支持工具的完整目录与仪表盘页面docs/guides/SETUP_GUIDE.md —— 安装方法与首次运行引导docs/guides/VSCODE-COPILOT.md —— OmniCopilot 扩展也可在编辑器内代你执行这些setup-*命令【免费下载链接】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），仅供参考