OmniRoute 安装教程:快速开始与 Claude Code 配置

OmniRoute 是一个 OpenAI 兼容的 AI 网关:把多个上游模型提供商统一成一个本地 API,Claude Code、Codex CLI、IDE 插件和你自己的脚本只需要配置一次地址。本文给出从安装到第一次成功请求的最短路径,完整的专题指南在独立站点维护。

先记住这两个地址

仪表板:http://localhost:20128
OpenAI 兼容 Base URL:http://localhost:20128/v1

配置客户端时填的是第二个,不是仪表板地址。

前置条件

Node.js >=22.22.2 <23 或 >=24.0.0 <27,推荐 24 LTS。版本不在这个范围内,仪表板可能白屏或报原生模块错误。需要时先安装 Node.js。
本地端口 20128 未被占用。
至少一个你打算通过 OmniRoute 路由的上游提供商账号或密钥。

安装并启动

任选一种方式:

# npm(推荐)
npm install -g omniroute
omniroute

# Docker
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

也可以从 OmniRoute GitHub Releases 下载 Windows、macOS 或 Linux 的 Desktop 安装包。:latest 指向最新已发布的稳定版,需要可复现部署时请固定到具体版本号。

启动后打开 http://localhost:20128。登录密码由 INITIAL_PASSWORD 环境变量决定;在上游的自托管配置里,首次启动会自动生成并打印到日志,Docker 部署时可以用 docker logs omniroute | grep -i password 查到。要让服务对外可达,务必先把它设成你自己的强密码。

连接提供商并创建密钥

在仪表板进入 Providers → Add Provider,选择并连接你的提供商。
在 API Keys 页面创建一个新密钥并保存好,它只会显示一次。这个密钥是客户端访问 OmniRoute 用的,不是上游提供商的密钥。

上游文档列出了一些无需密钥的免费提供商,可用性和条款会随时变化,使用前请自行核对对应服务的条款。

验证服务

export OMNIROUTE_API_KEY="粘贴你在 API Keys 页面创建的密钥"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

返回模型列表,说明 OpenAI 兼容端点和认证都正常。再发一个最小聊天请求,确认模型真的能被路由:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto 让 OmniRoute 按速度、成本和可用性自动选择提供商;也可以改成 /v1/models 返回的具体模型 ID。

接入你的工具

在任何支持 OpenAI 格式的工具里填入:

Base URL: http://localhost:20128/v1
API Key:  你创建的 OmniRoute 密钥
Model:    auto

OmniRoute 自带一键启动命令,例如 omniroute launch-codex --model auto,通用形式 omniroute run <target> 支持 claude、codex、aider、goose、opencode、qwen、gemini。想在 HagiCode 里使用的 Agent CLI,请先按 AI Agent CLI 安装准备好。

常见问题

仪表板白屏或提示 Node 版本不受支持:切换到 Node.js 24 LTS,重新执行 npm install -g omniroute,再运行 omniroute。
npm 11 下报找不到 better-sqlite3:npm 11 默认拦截可选依赖的安装脚本,按故障排查指南里的步骤手动重建。
macOS 报 slice is not valid mach-o file:在 $(npm root -g)/omniroute/app 下执行 npm rebuild better-sqlite3,再启动。