Flexgate

本地 Anthropic API 网关，根据请求中的 model 名称自动路由到不同的 provider。同时提供 Claude Code settings.json 的自动管理功能。

完整文档见 agony5757.github.io/flexible-gateway（Sphinx 构建，源文件在 docs/，随 main 分支自动发布）。

用途

Claude Code 只能配置一个 ANTHROPIC_BASE_URL，所有 tier（opus/sonnet/haiku）都指向同一个 provider。Flexgate 在本地启动一个 Anthropic 兼容端点，按 model 名称路由到不同 provider。

Claude Code → localhost:8765 → opus  → z.ai (glm-5.1)
                           → sonnet → minimax (MiniMax-M3)
                           → haiku  → minimax (MiniMax-M3)

运行原则：持久化只走 service。 Linux 上的持久化 serve 只由 systemd 用户服务 flexgate.service 管理。flexgate run 仅用于前台调试，不再创建第二套 PID/guardian 后台进程，因此不会再与 service 抢占同一端口。

安装

cd flexible-gateway
uv sync

源码开发时可以前台运行：

uv run flexgate config init
uv run flexgate run

日常使用推荐从 PyPI 全局安装，并交给 systemd 用户服务管理：

pipx install flexgate        # 或: uv tool install flexgate / pip install flexgate
flexgate config init
flexgate service install

从源码安装则用：uv tool install -e .

快速开始

# 1. 初始化配置文件（~/.flexgate/config.yaml）
flexgate config init
# 编辑 ~/.flexgate/config.yaml 填入你的 API key

# 2. 从已有 Claude Code 配置自动导入（可选）
flexgate settings import         # 读取 ~/.claude/settings.json* 中的凭证

# 3. 安装并启动唯一的持久化服务
# install 会询问是否将 Claude Code settings.json 指向本地网关
flexgate service install

# 4. 如果安装时跳过了 settings 修改，可稍后手动应用
flexgate settings apply

命令参考

服务管理（默认持久化模式）

systemd 用户服务是 Linux 上唯一推荐的持久化运行方式，负责开机/登录自启、崩溃重启、日志和进程生命周期。

flexgate service install             # 安装、启用并立即启动
flexgate service install --no-start  # 仅安装并启用，不立即启动
flexgate service install --no-claude-settings  # 跳过修改 ~/.claude/settings.json 的交互询问
flexgate service start               # 启动；自动修复旧格式或失效的 unit
flexgate service stop                # 停止
flexgate service restart             # 重启
flexgate service reload              # 热重载；host/port 变化时自动安全重启
flexgate service status              # 查看 systemd 状态和当前路由表
flexgate service uninstall           # 停止、禁用并删除 unit

说明：

• unit 写入 ~/.config/systemd/user/flexgate.service，直接运行前台 server，由 systemd 监督（Type=simple、Restart=on-failure）。
• install 会执行 loginctl enable-linger，使服务在未登录时仍保持运行并随开机启动。
• install --no-start 不会修改 Claude Code settings，避免把客户端指向尚未运行的 endpoint。
• unit 只能引用持久化配置路径；为避免重启后失效，/tmp 下的配置会被拒绝。
• start/restart 会清理旧 PID/guardian 残留、修复旧 unit 或已失效的配置路径，并在端口被其他进程占用时拒绝启动。
• 若升级时检测到旧版后台 gateway 仍在运行，会先准备好 systemd unit，但不会强杀正在服务的进程；按提示手动 kill <PID> 停掉旧进程，再执行 flexgate service start 完成切换。
• unit 设置了启动速率限制，永久配置错误不会再无限快速重启。
• service reload 和 config set/edit 会在仅路由变化时发送 SIGUSR1；如果 endpoint 变化，则先检查再 restart。若只改 host、仍复用当前 port，为避免误停服务会要求先执行 service stop，再执行 service start。
• 查看日志：flexgate log（-f 跟随、--since/--grep 过滤、-r 只看路由决策行）。

版本与升级

flexgate --version               # 打印版本号（service status / 裸 flexgate 也会显示）
flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings、上游连通性
flexgate doctor --offline        # 跳过全部网络检查（PyPI 新版检查 + 上游探测）
flexgate update                  # 一键升级：pip/pipx/uv 升级包 + 迁移配置 schema + 热重载服务
flexgate update --check          # 只报告将要做什么，不改动
flexgate update --config-only    # 只迁移配置，不升级包

升级策略：

• 包升级：版本号唯一来源是 flexgate/__init__.py；发布到 PyPI 后，flexgate update 自动检测安装方式（pipx / uv tool / pip）并升级到最新 release。
• 新版本自动提示：裸 flexgate 和 flexgate service status 会自动比对 PyPI 上的 最新版本，有新版时打印一行升级提示。检查结果缓存在 ~/.flexgate/update-check.json，每 24 小时最多访问一次 PyPI，离线时静默跳过。
• 配置迁移：config.yaml 带 config_version 标记。每次 schema 变化在 flexgate/migrate.py 的 MIGRATIONS 中登记一条 N → N+1 规则，升级时逐级走完整个迁移链。 迁移前自动备份为 config.yaml.bak-<时间戳>；配置比当前 flexgate 更新时会被拒绝并提示先升级。
• 自检：发版或排障时跑 flexgate doctor，有 FAIL 项时退出码为 1，可直接用于 CI 门禁。

发布流程（维护者）

仓库托管在 https://github.com/Agony5757/flexible-gateway，通过 GitHub Actions 自动发布到 PyPI（trusted publishing，无需 API token）：

# 1. 修改 flexgate/__init__.py 中的 __version__（唯一版本来源）
# 2. 提交后打 tag，tag 必须与 __version__ 一致（CI 会校验）
git tag v0.2.0
git push origin main --tags

推送 v* tag 触发 .github/workflows/release.yml：校验 tag 与 __version__ 一致 → 构建 sdist/wheel → 发布到 PyPI。首次发布前需在 PyPI 项目设置中配置 Trusted Publisher（repo: Agony5757/flexible-gateway，workflow: release.yml）。

上游连通性预检

运行 flexgate doctor 会向每个 被路由引用的 (provider, model) 组合 发送一次 POST /v1/messages（max_tokens=1，消耗约 1~2 token），用于主动检查：

• DNS / TCP / TLS 不可达（base_url 写错、网络不通）
• API key 无效或过期（HTTP 401 / 403）
• 仍是默认占位符（如 your-zai-api-key）
• Provider 侧 5xx 故障

可通过 --verify-timeout N 调整每个 provider 的超时时间（默认 15 秒）， --offline 跳过全部网络检查（PyPI 新版检查 + 上游探测）。 旧的 flexgate check 命令仍可用，但已弃用：它会打印提示并委托给 doctor （注意 doctor 还检查本地安装，退出码语义更宽）。

状态总览与用量查询（flexgate status / flexgate usage）

flexgate status                  # providers + fallback 链 + 每个 key 的用量 + 当前路由
flexgate status --no-usage       # 跳过用量查询，只看配置
flexgate status --usage-timeout 30
flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
flexgate usage --usage-timeout 30
flexgate usage --force           # 重查上次失败的 key（默认跳过，读缓存）

flexgate status 展示当前配置中的所有 provider、每个 provider 的 key 及 fallback 链、当前生效的路由，并逐一查询每个 key 的用量/额度； flexgate usage 只输出其中的用量部分。

各平台的用量查询方式差异很大，flexgate 按 base_url 自动选择适配器：

如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。 用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。

查询失败缓存：用量查询中报错的 key（彻底失败，或专用接口报错但 probe 证明 key 仍可用，例如智谱的按量付费 key）会记入 ~/.flexgate/usage-cache.json（只存 key 指纹，不存明文），此后 status / usage 默认跳过这些 key 并显示缓存错误与提示（cached failure）； flexgate usage --force 强制重查并更新缓存，干净成功后自动恢复实时查询。

HTTP API（图像生成与结构化错误）

除 POST /v1/messages 外，网关还提供 OpenAI 兼容的图像生成端点 POST /v1/images/generations：自动发现配置中的 MiniMax provider，把请求 翻译为 MiniMax image-01 文生图（模型名提示如 gpt-image/dall-e 均可， size 钳制到 512–2048 的 8 倍数，响应为 data[].b64_json）。 /v1/images/edits 固定返回 501（上游仅支持文生图）。

所有未支持的路径（如 /v1/chat/completions、/v1/embeddings、count_tokens） 返回 Anthropic/OpenAI 双兼容的结构化 JSON 错误（404/405/501），而不是裸 404。详见HTTP API 文档。

前台调试

run 是独立的顶层调试命令，不属于持久化服务模式：

flexgate run                       # 单个前台进程，仅用于开发/调试

非 systemd 环境只能使用 flexgate run 前台运行。--port PORT 也只对 run 生效；持久化服务的端口必须写入 server.port。

配置管理

flexgate config init             # 创建默认配置（~/.flexgate/config.yaml）
flexgate config show             # 查看当前配置（providers、路由、定时规则）
flexgate config edit             # 交互式选择每个 tier（opus/sonnet/haiku）的 provider/model
flexgate config path             # 打印配置文件路径
flexgate config set <tier> <target> [model]  # 快速设置路由（tier 可为 all/opus/sonnet/haiku）

config set 支持按 provider 名或 model 名设置路由：

# 批量切换所有 tier（opus/sonnet/haiku）到同一个 provider
flexgate config set all xiaomi

# 用逗号组合多个 tier
flexgate config set opus,sonnet xiaomi

# 按 provider 名 + model 名
flexgate config set sonnet minimax MiniMax-M3

# 按 provider 名（不改写 model）
flexgate config set opus zai

# 按 model 名自动查找 provider
flexgate config set haiku MiniMax-M3
# → 自动解析为 minimax / MiniMax-M3

# 如果 model 名在多个 provider 中存在，会提示歧义：
# Ambiguous: 'xxx' found in multiple providers:
#   flexgate config set haiku providerA xxx
#   flexgate config set haiku providerB xxx

注意：config set 不会修改 API key。如需添加新 provider 或修改密钥，请手动编辑配置文件。

交互式编辑（config edit）

运行 flexgate config edit 进入全屏交互界面，用 ↑/↓ 方向键移动、回车选择，无需记忆 provider/model 名称：

Flexgate config  —  ~/.flexgate/config.yaml
↑/↓ move · Enter edit · s save · q quit

▶ opus      ustc / deepseek-v4-pro
  sonnet    ustc / deepseek-v4-pro
  haiku     ustc / deepseek-v4-pro
  fallback  ustc / deepseek-v4-pro
  api keys  select the active key per route

○ no unsaved changes

• 方向键选中某个 tier（opus/sonnet/haiku）或 fallback（兜底路由 .*，未命中任何 tier 的请求走它），回车进入：先从候选 provider 列表选择，再从该 provider 的候选 model 列表选择。
• 选中 api keys 回车进入：先选一条路由，再选它的 active key；key 列表会实时查询每个 key 的用量/有效性（与 flexgate status 相同），并标注当前 active 的 key。
• model 列表包含：available_models 中的各个模型、「使用 provider 默认（首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
• 按 s 保存（并向运行中的网关发送 SIGUSR1 热重载，无需重启即生效），按 q 退出（有未保存改动时会询问 "Config changed — activate now?"：选 Yes 立即保存并热重载生效，选 No 放弃改动）；子菜单中按 Esc/← 返回上一级。
• 需要交互式终端（TTY）；非交互场景请改用 flexgate config set。

Settings 管理

flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml（多 key 追加）
flexgate settings apply          # 将网关 env 写入 ~/.claude/settings.json（非破坏性）
flexgate settings apply --dry-run  # 预览将要修改的 env 键，不写文件

apply 只重写 flexgate 托管的 6 个 env 键（BASE_URL、AUTH_TOKEN、 API_TIMEOUT_MS、三个 ANTHROPIC_DEFAULT_*_MODEL），settings.json 中的 其他字段（hooks、permissions、自定义 env 等）全部保留；写入前自动备份。 import 会把新 key 追加到 provider 的 api_keys 列表（已存在则跳过）， 不会覆盖已有 key。

全局参数

• --config PATH 指定配置文件（默认 ~/.flexgate/config.yaml）
• --port PORT 覆盖配置文件中的端口（仅 flexgate run）

配置文件

主要运行时资源：

旧版本的 ~/.flexgate/flexgate.pid、flexgate.guardian.pid 和 flexgate.log 不再属于当前运行架构；service 启动时会安全清理 PID 残留， 历史日志文件可按需手动删除。

运行 flexgate config init 创建默认配置，或手动编辑：

server:
  host: "127.0.0.1"
  port: 8765

providers:
  zai:
    base_url: "https://api.z.ai/api/anthropic"
    api_keys:
      - "your-zai-api-key"
  minimax:
    base_url: "https://api.minimaxi.com/anthropic"
    api_keys:                   # 同一上游可配多个 key，互为 fallback
      - key: "your-minimax-api-key"
        note: "主账号"          # 可选备注，存在配置里，status/日志中显示
      - key: "your-minimax-api-key-2"
        note: "备用账号"
      - "your-minimax-api-key-3"   # 纯字符串写法（无备注）

claude_settings:
  default_opus_model: "claude-opus-4-7"
  default_sonnet_model: "claude-sonnet-4-6"
  default_haiku_model: "claude-haiku-4-5"
  api_timeout_ms: 3000000

# 定时路由（可选）：按时间自动切换，首个时间窗口命中生效
# schedule:
#   - name: "night-shift"
#     start: "22:00"
#     end: "06:00"
#     routes:
#       - pattern: "^claude-sonnet"
#         provider: zai
#         model: "glm-5.1"

routes:                          # 从上到下匹配，首个命中生效
  - pattern: "^claude-opus"
    provider: zai
    model: "glm-5.1"            # 可选，发给 provider 的实际模型名
  - pattern: "^claude-sonnet"
    provider: minimax
    model: "MiniMax-M3"
    active_key: 2               # 可选：该路由从 minimax 的第 2 个 key 开始用（1 起始，默认 1）
  - pattern: "^claude-haiku"
    provider: minimax
    model: "MiniMax-M3"
  - pattern: ".*"               # 兜底
    provider: minimax
    model: "MiniMax-M3"

配置字段说明

Key fallback

同一上游有多个账号/key 时（例如多个 MiniMax 订阅），在 api_keys 里配 多个 key，而不是拆成多个 provider。每项可以是纯 key 字符串，也可以写成 {key, note} 加一个存在配置里的备注（flexgate status 和 fallback 日志 都会显示 note，方便分辨是哪个账号的 key）：

• 每条路由有一个「当前 key」指针（路由上的 active_key，默认指向 provider 的第一个 key）：该路由的请求从指针指向的 key 开始；key 失败 时自动换用下一个 key（循环一圈），指针也随之自动前进——后续请求直接 从能用的 key 开始。所有 key 轮换一圈都失败时，请求返回最后一次的 错误。指针的运行时前进只存在于网关进程内存中，不写回配置文件； 可通过 flexgate config edit → "api keys" 交互切换。
• 请求先走 active key；失败时按列表顺序自动重试后续 key，直到某个 key 成功或返回不可重试的错误。
• 触发切换的条件：HTTP 401 / 402 / 403 / 429 / 500 / 502 / 503 / 529 （key 失效、余额/额度耗尽、限流、平台过载）以及连接错误、超时。 其他 4xx（如 400 请求格式错误）不会触发切换。
• 流式请求只有在上游返回非 200 状态码之前才能切换 key；一旦开始吐 token，响应已提交，无法再 fallback。
• 每次切换都会在服务日志中留下记录（key 只显示前后各 4 位）。
• 用 flexgate status 可以查看每个 provider 的 fallback 链和每个 key 的 实时用量。
• 旧版 api_key + fallback_keys 写法仍然兼容，flexgate update 会 自动迁移为 api_keys 列表（config_version 3 → 4）。

Settings Import

flexgate settings import 会扫描 ~/.claude/settings.json*，从每个文件中提取 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，自动写入 config.yaml 的 providers 部分。

文件名与 provider 名称的映射规则：

• settings.json → 根据域名自动推断（如含 z.ai → zai）
• settings.json.zai → provider 名 zai
• settings.json.minimax → provider 名 minimax
• settings.json.bak.* → 跳过（备份文件）

适合场景：你有多套 Claude Code 配置文件，想要快速将凭证合并到网关中统一管理。

Settings Apply

flexgate settings apply 会：

1. 读取 config.yaml 中的 server 和 claude_settings
2. 备份当前 ~/.claude/settings.json 为 settings.json.bak.{timestamp}
3. 生成新的 settings.json，将 ANTHROPIC_BASE_URL 指向本地网关
4. 保留原有的 permissions 等非 env 字段

生成的 settings.json 示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8765",
    "ANTHROPIC_AUTH_TOKEN": "gateway",
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  },
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

ANTHROPIC_AUTH_TOKEN 值任意但不能为空，网关会替换为对应 provider 的 key。

环境变量

注意事项

• 配置默认存放在 ~/.flexgate/，全局安装后可在任意目录管理 systemd 用户服务
• Linux 持久化运行统一使用 flexgate service；不要额外启动独立后台进程
• config.yaml 已加入 .gitignore，不会被提交到 Git
• 请使用 config.yaml.template 作为参考模板
• 如果 API 密钥曾经被推送到远程仓库，请立即轮换（rotate）该密钥