OmniRoute CLI 集成指南：用 setup-* 与 omniroute run 将任意编码 CLI 指向统一网关
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, 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、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给出实现级证据。一、总览一条命令族统一所有编码 CLIOmniRoute 的 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 CLIomniroute run、omniroute configure与omniroute completion都从这份 manifest 派生目标列表与别名解析而不是各自维护一份拷贝见 bin/cli/cli-manifest.mjs 头部注释。历史上按工具单独提供的omniroute launchClaude Code与omniroute launch-codexCodex依然保留可用。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 remoteomniroute 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——包含目录中每个模型的omnirouteprovideropencode -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模型Key 经${{ 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-compatproviderKey 经$OMNIROUTE_API_KEY--remote--api-key--only--dry-run--port--config-path两者omniroute setup-gooseGoose~/.config/goose/config.yamlGOOSE_PROVIDER/OPENAI_HOST/GOOSE_MODEL 打印 env 配方--remote--api-key--model--yes--dry-run--port--config-path两者omniroute setup-aiderAider~/.aider.conf.ymlopenai-api-basemodel: openai/id 打印 env 配方--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运行时启动通用不写文件——以正确 env 与参数拉起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两者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.mjsaider收到--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报显式错误。该必须带模型的判断由 manifest 中的runModel.required字段驱动见 bin/cli/cli-manifest.mjs 的manifestRequiresModel。--port port本地 OmniRoute 端口默认20128设置--remote时忽略。所有setup-*与两个 launch 启动器都有。omniroute run退出码子 CLI 自身的退出码原样透传2 参数无效目标不支持、缺少必需的--model、容器保护127 目标二进制不在PATH130/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 v1omniroute/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_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-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 diffrun.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 约定哪些工具需要/v1OmniRoute 在/v1暴露 OpenAI 兼容面、在根路径暴露 Anthropic 兼容面、在/v1beta暴露原生 Gemini 面。每条集成都按工具预期形式接线在命令源码中已验证集成写入的 Base URL带/v1setup-clineopenAiBaseUrlroot否——Cline 自己追加/v1/chat/completionssetup-gooseOPENAI_HOSTroot否——Goose 自己追加路径setup-aiderOPENAI_API_BASEroot否——LiteLLM 追加/v1/chat/completionssetup-kilo、setup-roo、setup-continue、setup-crush、setup-cursor带/v1是setup-claudeANTHROPIC_BASE_URL、launchroot否——Claude Code 追加/v1/messagessetup-codex、launch-codexmodel_providers.omniroute.base_url带/v1是setup-qwenmodelProviders.openai[].baseUrl带/v1是run geminiGOOGLE_GEMINI_BASE_URLroot否——SDK 追加/v1beta/models/…理解这张表的价值在于如果你要手写配置而非使用 setup 命令就能据此正确拼装 Base URL避免 404 或协议不匹配。六、升级时保住原生依赖--includeoptional用omniroute update确认后或加--apply升级时OmniRoute 会内置执行带--includeoptional的安装npm install -g omniroutelatest --includeoptional这不是传给omniroute update的旗标——它由 updater 恒定应用。它保证optionalDependenciesbetter-sqlite3、keytar、tls-client、LLMLingua SLM 栈在升级后存活即使你的 npm 配置有omitoptional——否则原生 SQLite 驱动与 OS 钥匙串绑定会被静默移除。只想预览不执行omniroute update --dry-run # [DRY RUN] 将执行: npm install -g omniroutelatest --includeoptionalomniroute 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?altsse——正是 OmniRoute 的原生 Gemini 面/v1beta。omniroute run gemini自动完成以下接线GOOGLE_GEMINI_BASE_URL→ 激活的 OmniRoute Base URL根路径不带/v1GEMINI_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_TYPEgemini-api-key兜底——其他run目标也针对各自的冲突变量做同样处理从--provider/--model注入--model id。omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p helloGemini 的 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 的 harnesstests/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 秒超时。九、延伸阅读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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考