Back to Details

omni-auth

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->
<!-- 由 src/lib/agentSkills/generator.ts 生成；手动编辑将被覆盖 -->

Overview

概述

Manage API key authentication and session tokens. Start here to authenticate requests via Bearer token, obtain session cookies, and configure login requirements for the OmniRoute API.
管理 API key 认证和 session token。请从此处开始，通过 Bearer Token 认证请求、获取 session cookie，并为 OmniRoute API 配置登录要求。

Authentication

认证

Remote API requests use a Bearer credential. Dashboard login is different: 
POST /api/auth/login
accepts a management password and returns an 
auth_token
session cookie.
远程 API 请求使用 Bearer credential。Dashboard 登录有所不同：
POST /api/auth/login
接受管理密码，并返回一个 
auth_token
session cookie。

Endpoints

端点

POST /api/auth/login

POST /api/auth/login

Authenticate user
bash
curl -X POST http://localhost:20128/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookie.jar \
  -d '{"password":"<management-password>"}'
认证用户
bash
curl -X POST http://localhost:20128/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookie.jar \
  -d '{"password":"<management-password>"}'

POST /api/auth/logout

POST /api/auth/logout

Log out
bash
CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/logout \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
退出登录
bash
CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/logout \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/auth/oidc/login

GET /api/auth/oidc/login

Start OIDC login for the dashboard admin gate
Builds an authorization URL from the configured OIDC issuer/client (discovered via 
{issuer}/.well-known/openid-configuration
, falling back to 
{issuer}/authorize
), sets a short-lived 
oidc_state
cookie, and redirects the browser. Password login remains available as a fallback while OIDC is enabled.
bash
curl http://localhost:20128/api/auth/oidc/login \
  -b cookie.jar
为 Dashboard 管理员访问控制启动 OIDC 登录
根据配置的 OIDC issuer/client 构建 authorization URL（通过 
{issuer}/.well-known/openid-configuration
发现，失败时回退到 
{issuer}/authorize
），设置短期有效的 
oidc_state
cookie，并将浏览器重定向。启用 OIDC 时，密码登录仍可作为回退方案。
bash
curl http://localhost:20128/api/auth/oidc/login \
  -b cookie.jar

GET /api/auth/oidc/callback

GET /api/auth/oidc/callback

Complete OIDC login for the dashboard admin gate
Validates the 
state
cookie, exchanges the authorization 
code
for tokens, verifies the ID token against the issuer's JWKS (audience = client id), and checks the token's 
sub
/
email
against 
oidcAllowedSubjects
, which must hold at least one entry (an empty list ends in 
not_configured
). On success it mints the same 30-day 
auth_token
dashboard-session JWT used by password login and redirects to 
/dashboard
.
bash
curl http://localhost:20128/api/auth/oidc/callback \
  -b cookie.jar
完成 Dashboard 管理员访问控制的 OIDC 登录
验证 
state
cookie，将 authorization 
code
交换为 token，根据 issuer 的 JWKS 验证 ID token（audience = client id），并将 token 的 
sub
/
email
与 
oidcAllowedSubjects
进行比对；后者必须至少包含一个条目（空列表最终返回 
not_configured
）。成功后，它会签发与密码登录相同的 30 天有效期 
auth_token
Dashboard-session JWT，并将浏览器重定向到 
/dashboard
。
bash
curl http://localhost:20128/api/auth/oidc/callback \
  -b cookie.jar

GET /api/auth/csrf

GET /api/auth/csrf

GET auth › csrf
bash
curl http://localhost:20128/api/auth/csrf \
  -b cookie.jar
GET auth › csrf
bash
curl http://localhost:20128/api/auth/csrf \
  -b cookie.jar

GET /api/auth/status

GET /api/auth/status

GET auth › status
bash
curl http://localhost:20128/api/auth/status \
  -b cookie.jar
GET auth › status
bash
curl http://localhost:20128/api/auth/status \
  -b cookie.jar

Payloads

载荷

See the full OpenAPI specification at 
GET /api/openapi/spec
or 
docs/openapi.yaml
for detailed request/response schemas.
<!-- skill:custom-start --> <!-- Migrated from skills/omniroute/SKILL.md (preserved curated content) -->
有关详细的请求/响应 schema，请参阅完整的 OpenAPI specification：
GET /api/openapi/spec
或 
docs/openapi.yaml
。
<!-- skill:custom-start --> <!-- 从 skills/omniroute/SKILL.md 迁移而来（保留了已整理的内容） -->

OmniRoute

OmniRoute

Local/remote AI gateway exposing OpenAI-compatible REST. One key, 375 providers, auto-fallback, RTK token saver, MCP server, A2A agents.
本地/远程 AI gateway，提供兼容 OpenAI 的 REST 接口。一个 key 接入 375 个 provider，支持 auto-fallback、RTK token saver、MCP server 和 A2A agents。

Setup

设置

bash
export OMNIROUTE_URL="http://localhost:20128"      # or VPS / tunnel URL
export OMNIROUTE_KEY="sk-..."                       # from Dashboard → API Keys
All requests: 
${OMNIROUTE_URL}/v1/...
with 
Authorization: Bearer ${OMNIROUTE_KEY}
.
Verify: 
curl $OMNIROUTE_URL/api/health
→ 
{"ok":true}
bash
export OMNIROUTE_URL="http://localhost:20128"      # or VPS / tunnel URL
export OMNIROUTE_KEY="sk-..."                       # from Dashboard → API Keys
所有请求：
${OMNIROUTE_URL}/v1/...
，并设置 
Authorization: Bearer ${OMNIROUTE_KEY}
。
验证：
curl $OMNIROUTE_URL/api/health
→ 
{"ok":true}

Discover models

发现模型

bash
curl $OMNIROUTE_URL/v1/models                  # chat/LLM (default)
curl $OMNIROUTE_URL/v1/models/image            # image-gen
curl $OMNIROUTE_URL/v1/models/tts              # text-to-speech
curl $OMNIROUTE_URL/v1/models/embedding        # embeddings
curl $OMNIROUTE_URL/v1/models/web              # web search + fetch
curl $OMNIROUTE_URL/v1/models/stt              # speech-to-text
Use 
data[].id
as 
model
field in requests. Combos appear with 
owned_by:"combo"
.
bash
curl $OMNIROUTE_URL/v1/models                  # chat/LLM (default)
curl $OMNIROUTE_URL/v1/models/image            # image-gen
curl $OMNIROUTE_URL/v1/models/tts              # text-to-speech
curl $OMNIROUTE_URL/v1/models/embedding        # embeddings
curl $OMNIROUTE_URL/v1/models/web              # web search + fetch
curl $OMNIROUTE_URL/v1/models/stt              # speech-to-text
在请求中使用 
data[].id
作为 
model
字段。Combo 会显示为 
owned_by:"combo"
。

Capability skills

能力 skills

CapabilityRaw URL
Chat / code-genhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Image generationhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Text-to-speechhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Speech-to-texthttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Embeddingshttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Web searchhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Web fetchhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
MCP server (110 tools)https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-mcp/SKILL.md
A2A protocolhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-agents-a2a/SKILL.md
Routing & comboshttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-combos-routing/SKILL.md
Token compressionhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-compression/SKILL.md
Monitoring & healthhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-resilience/SKILL.md
能力原始 URL
Chat / 代码生成https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
图像生成https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
文本转语音https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
语音转文本https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Embeddingshttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Web 搜索https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
Web 抓取https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md
MCP server（110 个工具）https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-mcp/SKILL.md
A2A 协议https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-agents-a2a/SKILL.md
路由与组合https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-combos-routing/SKILL.md
Token 压缩https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-compression/SKILL.md
监控与健康状态https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-resilience/SKILL.md

CLI skills (omniroute binary)

CLI skills（omniroute binary）

CapabilityRaw URL
CLI entry pointhttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md
CLI admin & lifecyclehttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md
CLI providers & keyshttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-providers/SKILL.md
CLI cloud agents (
omniroute cloud …
)		https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-backup-sync/SKILL.md
CLI evals & benchmarkshttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-eval/SKILL.md
能力原始 URL
CLI 入口点https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md
CLI 管理与生命周期https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md
CLI providers 与 keyshttps://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-providers/SKILL.md
CLI cloud agents（
omniroute cloud …
）		https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-backup-sync/SKILL.md
CLI 评测与基准测试https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-eval/SKILL.md

Errors

错误

  • 401
    → set/refresh 
    OMNIROUTE_KEY
    (Dashboard → API Keys)
  • 400 Invalid model format
    → check 
    model
    exists in 
    /v1/models/<kind>
  • 503 Provider circuit open
    → upstream provider down; retry after 
    Retry-After
    seconds
  • 429
    → rate limited; honor 
    Retry-After
  • 401
    → 设置/刷新 
    OMNIROUTE_KEY
    （Dashboard → API Keys）
  • 400 Invalid model format
    → 检查 
    model
    是否存在于 
    /v1/models/<kind>
  • 503 Provider circuit open
    → 上游 provider 已故障；在 
    Retry-After
    指定的秒数后重试
  • 429
    → 受到限流；请遵守 
    Retry-After

Differentiators vs OpenAI direct

相较于直接使用 OpenAI 的差异化特性

  • Auto-fallback combos (19 strategies): never stop coding even if a provider rate-limits
  • RTK token saver: tool_result compressed via 47 specialized filters (git-diff, test-jest, terraform-plan, docker-logs…) — 20-40% token reduction
  • Caveman mode: optional terse system prompt injection (LITE/FULL/ULTRA) — 15-25% completion reduction
  • MCP + A2A servers built-in (this is the only AI router that exposes both protocols)
  • Memory with FTS5 + Qdrant for persistent agent context
  • Guardrails for PII masking, prompt injection detection, vision policies
<!-- skill:custom-end -->
  • Auto-fallback 组合（19 种策略）：即使某个 provider 受到限流，也不会停止编码
  • RTK token saver：通过 47 种专用过滤器（git-diff、test-jest、terraform-plan、docker-logs……）压缩 tool_result — Token 减少 20-40%
  • Caveman mode：可选的简洁 system prompt 注入（LITE/FULL/ULTRA）— completion 减少 15-25%
  • 内置 MCP + A2A server（这是唯一同时暴露两种协议的 AI router）
  • Memory 使用 FTS5 + Qdrant，为 agent 提供持久化上下文
  • Guardrails：支持 PII 掩码、prompt injection 检测和 vision 策略
<!-- skill:custom-end -->