使用你自己的 OpenAI、Anthropic 或 Google API 密钥配合 BitRouter。在你自己的基础设施上运行代理，完全掌控路由和部署。

没有自己的 API 密钥？改用 BitRouter Cloud — 无需提供商密钥。

Agent Skills（推荐）

最快的设置路径。安装 BitRouter Agent Skills，让你的 Agent 处理剩下的一切：

npx skills add bitrouter/agent-skills

或手动安装：

# Claude Code
cp -r skills/bitrouter ~/.claude/skills/

# VS Code / GitHub Copilot
cp -r skills/bitrouter .github/skills/

# Cursor
cp -r skills/bitrouter .cursor/skills/

然后将以下提示词粘贴到你的 Agent 中：

Set up BitRouter as my local LLM proxy. Install it, configure providers
with my existing API keys, start the server, and verify it's working.

你的 Agent 会自动安装 BitRouter、检测 API 密钥、生成配置、启动代理，并验证健康检查端点——全程自主完成。

安装

前提条件

Rust 工具链（stable，1.80+）

从 crates.io 安装

cargo install bitrouter

此命令会将 bitrouter 二进制文件构建并安装到 ~/.cargo/bin。

从源码安装

git clone https://github.com/bitrouter/bitrouter.git
cd bitrouter
cargo build --release

二进制文件位于 target/release/bitrouter。将其复制到 PATH 或直接运行。

功能标志

功能	默认	描述
`tui`	是	交互式终端界面
`swig`	否	链上 Swig 钱包操作（需要 Solana 依赖）

不包含 TUI 的构建：

cargo build --release --no-default-features

包含 Swig 钱包支持的构建：

cargo build --release --features swig

验证

bitrouter status

更新

cargo install bitrouter

BitRouter 会自动检查新版本，并在有更新可用时打印提示。

启动

# 交互模式：首次运行时执行设置向导，然后启动 TUI + API 服务器
bitrouter

# 无 TUI 的 API 服务器
bitrouter serve

# 后台守护进程
bitrouter start

首次启动时如果没有配置提供商，BitRouter 会自动运行交互式设置向导。选择提示时请选择 Bring Your Own Key。你也可以显式运行向导：

bitrouter init

零配置模式

如果你的环境中已有提供商 API 密钥，BitRouter 会自动检测并启用直接路由，无需任何配置文件：

export OPENAI_API_KEY=sk-...
bitrouter serve
# 使用 "openai:gpt-4o" 作为模型名称

配置

主目录

BitRouter 按以下顺序解析工作目录：

命令行指定 --home-dir <PATH>
当前目录（如果存在 ./bitrouter.yaml）
BITROUTER_HOME 环境变量（如果指向已存在的目录）
~/.bitrouter（默认回退 — 首次运行时自动创建）

目录结构

<home>/
├── bitrouter.yaml   # 主配置文件
├── .env             # 环境变量（自动加载，已被 git 忽略）
├── .gitignore       # 忽略 .env、logs/、run/、.keys/、bitrouter.db
├── run/             # PID 文件、Unix 套接字、运行时状态
├── logs/            # 服务器日志
└── bitrouter.db     # SQLite 数据库（默认，自动创建）

环境变量

BitRouter 启动时自动加载 <home>/.env。进程环境变量优先于 .env 中的值。在 bitrouter.yaml 中使用 ${VAR} 占位符：

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    api_base: ${OPENAI_BASE_URL}

替换规则：

优先级： 进程环境 > .env 文件
语法： 在任何 YAML 字符串值中使用 ${VAR_NAME}
缺失变量： 替换为空字符串（不报错）
递归： 在嵌套对象和数组中均有效

.env 文件可能包含敏感信息。默认的 .gitignore 已将其排除 — 请勿提交到版本控制。

关键环境变量

变量	描述
`BITROUTER_HOME`	覆盖主目录
`BITROUTER_DATABASE_URL`	数据库连接 URL（覆盖配置中的 `database.url`）
`OWS_PASSPHRASE`	钱包解密密码（未设置且有 TTY 时会提示输入）
`MPP_SECRET_KEY`	MPP 挑战验证的 HMAC 密钥
`{PREFIX}_API_KEY`	提供商 API 密钥（如 `OPENAI_API_KEY`、`ANTHROPIC_API_KEY`）
`{PREFIX}_BASE_URL`	提供商 Base URL 覆盖（如 `OPENAI_BASE_URL`）

最小 `bitrouter.yaml` 配置

server:
  listen: 127.0.0.1:8787

providers:
  openai:
    api_key: ${OPENAI_API_KEY}

models:
  default:
    strategy: priority
    endpoints:
      - provider: openai
        model_id: gpt-4o

BitRouter 支持空配置文件运行 — 甚至完全不需要配置文件。所有内置提供商（OpenAI、Anthropic、Google、OpenRouter、DeepSeek 等）在环境中设置 API 密钥后均自动可用。

完整配置参考

bitrouter.yaml 中所有可用的部分和字段：

# ── 服务器 ──────────────────────────────────────────────────────────

server:
  listen: "127.0.0.1:8787" # HTTP API 服务器地址和端口
  log_level: info # trace | debug | info | warn | error
  control:
    socket: bitrouter.sock # 守护进程控制 Unix 套接字

# ── 数据库 ──────────────────────────────────────────────────────────

database:
  # 连接 URL。支持 sqlite://、postgres://、mysql://。
  # 优先级：--db 标志 > BITROUTER_DATABASE_URL 环境变量 > 此字段 > 默认 SQLite
  url: "sqlite://bitrouter.db?mode=rwc"

# ── 提供商继承 ──────────────────────────────────────────────────────

# 内置提供商：openai、anthropic、google、openrouter、deepseek、
# minimax、zai、moonshot、qwen、bitrouter（300+ 聚合模型）。
# 设为 false 则仅使用下方声明的提供商。
inherit_defaults: true

# ── 提供商 ──────────────────────────────────────────────────────────

providers:
  # 覆盖内置提供商（只修改你设置的字段）。
  openai:
    api_key: "${OPENAI_API_KEY}"

  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

  google:
    api_key: "${GOOGLE_API_KEY}"

  # 从内置提供商继承的自定义提供商。
  my-proxy:
    derives: openai
    api_base: "https://api.mycompany.com/v1"
    api_key: "${MY_PROXY_API_KEY}"

  # 完全自定义提供商（无继承）。
  custom-llm:
    api_protocol: openai # openai | anthropic | google | mcp | rest
    api_base: "https://llm.example.com/v1"
    api_key: "${CUSTOM_LLM_KEY}"
    env_prefix: CUSTOM_LLM # 自动读取 CUSTOM_LLM_API_KEY / CUSTOM_LLM_BASE_URL
    default_headers:
      x-project-id: "my-project"
    models:
      my-model-7b:
        name: "My Model 7B"
        description: "自定义微调模型"
        max_input_tokens: 32768
        max_output_tokens: 4096
        input_modalities: [text]
        output_modalities: [text]
        pricing:
          input_tokens:
            no_cache: 0.50 # 每百万 token（美元）
            cache_read: 0.25
            cache_write: 0.75
          output_tokens:
            text: 1.50
            reasoning: 3.00

  # MCP 工具提供商（桥接模式）。
  github-mcp:
    api_protocol: mcp
    api_base: "https://api.githubcopilot.com/mcp"
    api_key: "${GITHUB_TOKEN}"
    bridge: true # 暴露为 POST /mcp/github-mcp

  # 使用自定义 Header 认证的提供商。
  header-auth-provider:
    derives: openai
    api_base: "https://api.example.com/v1"
    auth:
      type: header
      header_name: "x-api-key"
      api_key: "${HEADER_AUTH_KEY}"

  # 使用 MPP（机器支付协议）认证的提供商。
  paid-provider:
    derives: openai
    api_base: "https://paid.example.com/v1"
    auth:
      type: mpp

# ── 模型路由 ────────────────────────────────────────────────────────

models:
  smart:
    strategy: priority
    endpoints:
      - provider: anthropic
        service_id: claude-sonnet-4-20250514
      - provider: openai
        service_id: gpt-4o
    name: "Smart"
    max_input_tokens: 200000
    max_output_tokens: 16384

  fast:
    strategy: load_balance
    endpoints:
      - provider: openai
        service_id: gpt-4o-mini
        api_key: "${OPENAI_KEY_POOL_A}"
      - provider: openai
        service_id: gpt-4o-mini
        api_key: "${OPENAI_KEY_POOL_B}"

  coding:
    strategy: priority
    endpoints:
      - provider: anthropic
        service_id: claude-sonnet-4-20250514
      - provider: openai
        service_id: gpt-4o
      - provider: google
        service_id: gemini-2.5-pro

# ── 工具路由 ────────────────────────────────────────────────────────

tools:
  create_issue:
    strategy: priority
    endpoints:
      - provider: github-mcp
        service_id: create_issue
    description: "创建 GitHub issue"
    input_schema:
      type: object
      properties:
        repo: { type: string }
        title: { type: string }
        body: { type: string }
      required: [repo, title]
    skill: "github-issues"

  web_search:
    endpoints:
      - provider: exa
        service_id: search
    pricing:
      default: 0.001
      overrides:
        search: 0.002

# ── 护栏 ────────────────────────────────────────────────────────────

guardrails:
  enabled: true

  disabled_patterns:
    - ip_addresses
    - pii_phone_numbers

  custom_patterns:
    - name: internal_token
      regex: "myapp_[A-Za-z0-9]{32}"
      direction: upgoing

  upgoing:
    api_keys: redact
    private_keys: block
    credentials: redact

  downgoing:
    suspicious_commands: block

  custom_upgoing:
    internal_token: block

  block_message:
    include_details: true
    include_help_link: true

  tools:
    enabled: true
    providers:
      github-mcp:
        filter:
          deny: [delete_repo, delete_branch]
        param_restrictions:
          rules:
            create_issue:
              deny: [assignees]
              action: strip

# ── 钱包 ────────────────────────────────────────────────────────────

wallet:
  name: "my-wallet"
  vault_path: "~/.ows"
  payment:
    tempo_rpc_url: "https://rpc.moderato.tempo.xyz"
    solana_rpc_url: "https://api.mainnet-beta.solana.com"
    session_max_deposit: 10000000
    session_default_deposit: 1000000

# ── MPP（机器支付协议） ────────────────────────────────────────────

mpp:
  enabled: true
  realm: "bitrouter.example.com"
  secret_key: "${MPP_SECRET_KEY}"
  networks:
    tempo:
      recipient: "0x1234..."
      escrow_contract: "0xabcd..."
      rpc_url: "${TEMPO_RPC_URL}"
      currency: "${TEMPO_TOKEN_ADDRESS}"
      fee_payer: false
      default_deposit: "5000000"

# ── Solana RPC ──────────────────────────────────────────────────────

solana_rpc_url: "https://api.mainnet-beta.solana.com"

配置加载流程

加载环境 — 读取 .env 文件，然后读取进程环境（进程环境优先）
替换 ${VAR} — 替换 YAML 中所有变量引用
解析 YAML — 反序列化为配置结构
合并内置提供商 — 除非 inherit_defaults: false
解析 derives — 展平提供商继承链
应用 env_prefix — 自动读取 {PREFIX}_API_KEY / {PREFIX}_BASE_URL

热重载

运行中的服务器可以无停机重载配置：

bitrouter reload
# 或向服务器进程发送 SIGHUP

热重载会重新读取配置文件并更新路由表、护栏和工具注册表。动态路由（通过 bitrouter route add 添加的）在重载后保留，但进程重启后不保留。

模型提供商

内置提供商

提供商	协议	环境前缀	自动检测的密钥
`openai`	OpenAI	`OPENAI`	`OPENAI_API_KEY`
`anthropic`	Anthropic	`ANTHROPIC`	`ANTHROPIC_API_KEY`
`google`	Google	`GOOGLE`	`GOOGLE_API_KEY`
`openrouter`	OpenAI	`OPENROUTER`	`OPENROUTER_API_KEY`

内置提供商包含完整的模型目录（上下文长度、模态）和 token 定价。你只需提供 API 密钥。

自定义提供商

任何 OpenAI 兼容或 Anthropic 兼容的 API 都可以通过 derives 字段接入：

providers:
  my-company:
    derives: openai
    api_base: "https://api.mycompany.com/v1"
    api_key: "${MY_COMPANY_API_KEY}"

  moonshot:
    derives: anthropic
    api_base: "https://api.moonshot.ai/anthropic"
    api_key: "${MOONSHOT_API_KEY}"

提供商字段

字段	描述
`derives`	从另一个提供商定义继承
`api_protocol`	`openai`、`anthropic` 或 `google`
`api_base`	上游 API 的基础 URL
`api_key`	默认 API 密钥
`env_prefix`	从环境自动加载 `{PREFIX}_API_KEY` 和 `{PREFIX}_BASE_URL`
`default_headers`	每个请求附带的额外 HTTP 头
`auth`	认证方式覆盖
`models`	每个模型的元数据和定价目录
`bridge`	仅 MCP：暴露为 `POST /mcp/{name}`

认证模式

# 默认：Bearer token（设置 api_key 时自动使用）
providers:
  example-bearer:
    api_key: "sk-..."

# 自定义头（如 x-api-key）
providers:
  example-header:
    auth:
      type: header
      header_name: "x-api-key"
      api_key: "key-..."

# 自定义认证（如 x402 或 SIWx）
providers:
  example-custom:
    auth:
      type: custom
      method: siwx
      params:
        chain_id: 1

模型路由

定义虚拟模型名称，路由到一个或多个提供商端点：

models:
  default:
    strategy: priority
    endpoints:
      - provider: openai
        model_id: gpt-4o
      - provider: anthropic
        model_id: claude-sonnet-4-20250514

  fast:
    strategy: load_balance
    endpoints:
      - provider: openai
        model_id: gpt-4o-mini
        api_key: "sk-key-a"
      - provider: openai
        model_id: gpt-4o-mini
        api_key: "sk-key-b"

策略	行为
`priority`	按顺序尝试端点；出错时故障转移到下一个
`load_balance`	通过轮询均匀分配请求

每个端点可以独立覆盖 api_key 和 api_base，适用于在多个 API 密钥之间分散负载。

直接路由

跳过 models 部分，直接使用 provider:model_id 语法：

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "openai:gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

动态路由

在运行时添加或移除路由，无需重启：

bitrouter route list
bitrouter route add research openai:o3 anthropic:claude-sonnet-4-20250514 --strategy priority
bitrouter route rm research

动态路由存储在内存中，重启后重置。

CLI 参考

服务器生命周期

命令	功能描述
`init`	交互式提供商配置设置向导
`serve`	在前台启动 API 服务器
`start`	以后台守护进程方式启动 BitRouter
`stop`	停止运行中的守护进程
`status`	打印解析路径、监听地址、已配置提供商和守护进程状态
`restart`	重启后台守护进程
`reload`	无停机热重载配置

账户管理

bitrouter account -g            # 生成新密钥对
bitrouter account -l            # 列出所有密钥对
bitrouter account --set <ID>    # 通过索引或公钥前缀设置活跃账户

每个账户都有 Solana 地址、EVM 地址和公钥前缀。密钥存储在 ~/.bitrouter/.keys/。

令牌生成

使用活跃账户创建签名 JWT：

bitrouter keygen --scope api --exp 30d --models "openai:*,anthropic:claude-*"

标志	描述
`--chain <CHAIN>`	签名链：`solana`（默认）或 `base`
`--scope <SCOPE>`	令牌范围：`api`（默认）或 `admin`
`--exp <EXP>`	过期时间：`5m`、`1h`、`30d`、`never`
`--models <MODELS>`	逗号分隔的模型模式
`--tools <TOOLS>`	逗号分隔的工具模式（如 `github/*,jira/search`）
`--budget <BUDGET>`	预算限额（微美元）
`--budget-scope <SCOPE>`	`session` 或 `account`
`--budget-range <RANGE>`	如 `rounds:10`、`duration:3600s`
`--name <LABEL>`	使用标签在本地保存令牌

bitrouter keys -l              # 列出已保存的令牌
bitrouter keys --show <ID>     # 显示解码后的 JWT 声明
bitrouter keys --rm <ID>       # 删除已保存的令牌

路由管理

bitrouter route list
bitrouter route add my-model openai:gpt-4o anthropic:claude-sonnet-4-20250514 --strategy priority
bitrouter route rm my-model

检查上游服务

bitrouter tools list      # 列出所有可用的 MCP 工具
bitrouter tools status    # 显示上游 MCP 服务器健康状态
bitrouter agents list     # 列出已配置的上游代理
bitrouter agents status   # 显示连接健康状态

全局标志

标志	描述
`--home-dir <PATH>`	覆盖 BitRouter 主目录
`--config-file <PATH>`	覆盖 `<home>/bitrouter.yaml`
`--env-file <PATH>`	覆盖 `<home>/.env`
`--run-dir <PATH>`	覆盖 `<home>/run`
`--logs-dir <PATH>`	覆盖 `<home>/logs`
`--db <DATABASE_URL>`	覆盖数据库连接 URL

TUI 仪表盘

不带参数运行 bitrouter 即可启动交互式 TUI，显示守护进程状态、监听地址、已配置的提供商和活跃路由。TUI 会根据终端宽度自适应布局。

按键	操作
`q`	退出
`Ctrl+C`	退出

如果未配置提供商，TUI 会自动启动设置向导。

TUI 是默认启用的可选功能。使用 cargo build --release --no-default-features 可不包含 TUI 构建。

集成

BitRouter 兼容 OpenAI，因此可与任何支持自定义 OpenAI 端点的工具配合使用。请参阅以下 AI 编码工具的集成指南：

OpenClaw

故障排除

如果你遇到任何问题，请通过 Discord 或 Twitter/X 联系我们。我们的团队将很乐意帮助你调试和解决问题。

接下来做什么？

OpenClaw 集成 - 通过 BitRouter 路由 OpenClaw Agent 请求
API 参考 - 完整的技术文档

手动指南