Auto Model Key Router

一个本地 OpenAI-compatible API 路由器：把多个模型和多个上游 API Key 统一收口到本地服务，自动分流、失败切换、统计调用，并可一键接入 Claude Code / Codex。

主要能力

  • 多 Key 路由：同一模型可配置多个 Key，支持 round_robin、priority、only_first。
  • 失败切换与冷却：遇到 401/403/429/5xx 等可重试错误时自动重试或切换 Key，并在进程内临时冷却异常 Key。
  • 统一模型名：客户端固定请求 unified-model，真实模型和固定 Key 可在路由器侧随时切换。
  • OpenAI-compatible 代理：支持 /v1/chat/completions、/v1/models，并兼容 Claude Code 的 /v1/messages 与 Codex 的 /v1/responses；可为不同协议模式配置上游额外路径。
  • Terminal UI 管理：在 TUI 中配置模型、Key、统一模型、服务注册和客户端接入。
  • 访客 Key：安装 visitor extra 后，可用固定访客 Key 暴露受限公共模型。
  • 统计与日志：记录本地/访客调用、模型、Key、状态码、token、重试、延迟等指标。

安装

需要 Python >=3.12。

使用 pipx：

pipx install auto-model-key-router
pipx ensurepath

或使用 uv：

uv tool install auto-model-key-router
uv tool update-shell

pipx ensurepath 和 uv tool update-shell 会把命令所在目录加入 PATH。执行后请关闭并重新打开终端（IDE、VS Code、Windows Terminal 也要重新启动），再验证：

amkr --version
# 备用命令
auto-model-key-router --version

Windows PowerShell 如果仍然提示“无法将 amkr 识别为命令”，先用下面的命令确认实际安装目录：

uv tool dir --bin
pipx environment --value PIPX_BIN_DIR

然后把输出目录加入当前用户的 PATH，并重新打开终端。也可以直接使用 PATH 无关的临时方式验证安装是否成功：

uvx --from auto-model-key-router amkr --version

如果 uvx 能运行而 amkr 不能运行，说明安装和 console script 没问题，缺的是 PATH。安装状态可分别用 pipx list 或 uv tool list 查看。

启用访客 Key 功能：

pipx install "auto-model-key-router[visitor]"
# 或
uv tool install "auto-model-key-router[visitor]"

快速开始

1. 启动 Terminal UI

amkr

首次启动会在系统缓存目录自动创建配置文件和本地鉴权 Key。你也可以复制示例配置到当前目录：

cp router-config.example.json router-config.json
amkr --config router-config.json

Windows PowerShell 可使用：

copy router-config.example.json router-config.json
amkr --config router-config.json

2. 配置模型与 Key

在 TUI 中进入：

  1. 模型 Key：添加真实模型和上游 API Key，并可在管理 Key 中对当前 Key 或所有 Key 探测 /v1/chat/completions、/v1/messages、/v1/responses 可用性。
  2. 统一模型：把 unified-model 指向一个真实模型，必要时固定到某个 Key。
  3. 一键配置 → 路由服务：启动或注册本地代理服务。
  4. 一键配置 → Claude Code / Codex / Pi Agent：按需自动写入客户端配置。

3. 调用本地代理

默认服务地址是：

http://127.0.0.1:8000

请求示例：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer amkr_your-local-api-key" \
  -d '{
    "model": "unified-model",
    "messages": [{"role": "user", "content": "hello"}]
  }'

也可以把 model 写成真实模型 ID、模型 alias，或 模型ID[key name] 来显式指定某个 Key。

常用命令

# 打开 TUI
amkr

# 使用指定配置文件打开 TUI
amkr --config router-config.json

# 后台启动 / 查看状态 / 停止
auto-model-key-router --config router-config.json --serve
auto-model-key-router --config router-config.json --status
auto-model-key-router --config router-config.json --stop

# 注册、管理系统服务
auto-model-key-router --config router-config.json --install-service
auto-model-key-router --config router-config.json --service status
auto-model-key-router --config router-config.json --service restart

# 查询 AMKR 监听 IP 和端口
auto-model-key-router --config router-config.json --show-address

# 获取当前 AMKR 的本地授权 Key（也可使用 --show-api-key）
auto-model-key-router --config router-config.json --get-key

# 查看配置摘要、日志与统计
auto-model-key-router --config router-config.json --show-config
auto-model-key-router --config router-config.json --show-logs 50

# 管理 unified-model
auto-model-key-router --config router-config.json --show-unified-model
auto-model-key-router --config router-config.json --switch-model gpt-4o-mini
auto-model-key-router --config router-config.json --switch-key auto

配置示例

{
  "config_version": 3,
  "host": "127.0.0.1",
  "port": 8000,
  "request_timeout": 60,
  "stream_first_byte_timeout": 90,
  "stream_idle_timeout": 180,
  "max_retries": 2,
  "key_failure_threshold": 2,
  "key_cooldown_seconds": 60,
  "local_api_key": "amkr_your-local-api-key",
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com",
      "routes": {
        "openai": "v1/chat/completions",
        "responses": "v1/responses"
      },
      "keys": {
        "main": {"api_key": "sk-your-first-upstream-key"},
        "backup": {"api_key": "sk-your-second-upstream-key"}
      },
      "pools": {
        "default": {
          "keys": ["main", "backup"],
          "available_models": ["gpt-4o-mini"],
          "models": ["gpt-4o-mini"]
        }
      }
    },
    "tokenplan": {
      "base_url": "https://example.com/tokenplan",
      "routes": {"anthropic": "anthropic/"},
      "keys": {
        "mimo": {"api_key": "sk-your-third-upstream-key"}
      },
      "pools": {
        "default": {"keys": ["mimo"]}
      }
    }
  },
  "unified_model": {
    "model": "gpt-4o-mini",
    "key": null
  },
  "models": {
    "gpt-4o-mini": {
      "aliases": ["fast-mini"],
      "routing_mode": "round_robin",
      "targets": [
        {"provider": "openai", "pool": "default", "upstream_model": "gpt-4o-mini"},
        {"provider": "tokenplan", "pool": "default", "upstream_model": "gpt-4o-mini"}
      ]
    }
  }
}

local_api_key 是客户端访问本地 AMKR 的 Key；providers.*.keys.*.api_key 是真实供应商 Key；providers.*.pools 表示同一模型能力池，TUI 创建或刷新模型池时会探测可用模型与路由并写入 available_models / routes 元信息，探测到的模型默认不启用；如果上游不支持 /v1/models，TUI 会允许手动填写可用模型并继续探测路由；providers.*.pools.*.models 是手动启用后可用于添加本地模型路由的模型清单。旧版 models[].keys[] 和 v2 的 target.key 会自动迁移为新版语义。

流式请求使用分段超时：stream_first_byte_timeout（默认 90 秒）覆盖等待上游响应头和第一块响应体的总时间，stream_idle_timeout（默认 180 秒）限制首块之后相邻响应块的等待时间，两者都必须大于 0。响应头返回前超时会按现有重试策略切换 Key；下游流建立后超时只结束当前流，不会自动重放请求。可在 TUI 的 CLI 设置 → 超时配置 中统一调整普通请求和两个流式超时。

文档

访客 Key 简介

安装 auto-model-key-router[visitor] 后，可以用固定 Key amkr-visitor 暴露受限公共模型。只有设置了 allow_visitor: true 的上游 Key 才能被访客使用，访客看到的模型名格式为 amkr-{真实模型ID}。

详细限制和示例见 完整使用教程：使用访客 Key。

开发

git clone https://github.com/sparr68/auto-model-key-router.git
cd auto-model-key-router
pip install -e ".[test]"
pytest

安全提示

  • 不要把真实上游 API Key 提交到 Git。
  • local_api_key 为空会关闭本地鉴权；仅建议在可信本机环境使用。
  • amkr --get-key / --show-api-key 会直接输出本地授权 Key，请勿在共享终端、日志或 CI 输出中执行。
  • 如果监听 0.0.0.0 或暴露到局域网/公网，请务必启用本地鉴权并配置防火墙。

License

MIT

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.2.9)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Sparrived from gravatar.com Sparrived

Credits

Author: Sparrived

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

visitor test release dev

Tags

openai api-key router fastapi cli tui

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

auto_model_key_router-3.2.8.tar.gz (205.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

auto_model_key_router-3.2.8-py3-none-any.whl (154.3 kB view details)

Uploaded Python 3

File details

Details for the file auto_model_key_router-3.2.8.tar.gz.

File metadata

  • Download URL: auto_model_key_router-3.2.8.tar.gz
  • Upload date:
  • Size: 205.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auto_model_key_router-3.2.8.tar.gz
Algorithm Hash digest
SHA256 44512cf10c159e9c4656eaf05c74c0b8bef10a927d369856a83336666cfe809e
MD5 9bb9cf84a8161ebcea5ba5b85298a5c1
BLAKE2b-256 f83ead243c637735d15a1ca6aaefdde695b080b46ece35e739963f4d4b779837

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto_model_key_router-3.2.8.tar.gz:

Publisher: publish-pypi.yml on Sparrived/auto-model-key-router

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auto_model_key_router-3.2.8-py3-none-any.whl.

File metadata

File hashes

Hashes for auto_model_key_router-3.2.8-py3-none-any.whl
Algorithm Hash digest
SHA256 6786c0e09816524550c597d703b382b4a16403149e25316c2ce93e6f1ca0a466
MD5 a73d39c70d52faee96b1be4c08c9a15d
BLAKE2b-256 0f30486a9b1c7771b21897250cdb5d358f2c283eabdcf43dfc52caff8572fd25

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto_model_key_router-3.2.8-py3-none-any.whl:

Publisher: publish-pypi.yml on Sparrived/auto-model-key-router

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.2.9

2 files

This release

3.2.8 This release

2 files

3.2.7

2 files

3.2.6

2 files

3.2.5

2 files

3.2.4

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.1

2 files

3.1.0

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

2.2.6

2 files

2.2.5.post1

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3.post1

2 files

2.2.3

2 files

2.2.2.post3

2 files

2.2.2.post2

2 files

2.2.2.post1

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.6

2 files

2.1.5.post1

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.2

2 files

2.0.0.post1

2 files

2.0.0

2 files

1.7.0

2 files

1.6.1.post2

2 files

1.6.1.post1

2 files

1.6.1

2 files

1.6.0

2 files

1.5.0

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

Pre-release

1.3.3a1

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.4

2 files

Pre-release

1.2.3rc3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page