passkey-proxy

Universal API key stripping proxy — 解决需要空 apikey 的模型无法被标准 OpenAI SDK 调用的问题。按 model 名称自动路由到对应上游，自动处理 API Key。

原理

客户端 (OpenAI SDK)  -->  passkey-proxy  -->  上游 API
  (带任意 apikey)        按 model 路由        (自动处理 key)

许多上游模型（如 opencode.ai）不需要或拒绝 API Key，但 OpenAI SDK 要求必须传一个非空值。passkey-proxy 充当中间层，接收客户端任意 API Key，根据请求中的 model 名称自动选择上游，并按照上游配置决定是否携带 Key。

安装

# 直接运行（不安装）
npx @wenlu8848/passkey-proxy

# 全局安装
npm install -g @wenlu8848/passkey-proxy
passkey-proxy

快速开始

创建 passkey-proxy.yaml：

port: 4000
level: info

cors:
  enabled: true
  origins: "*"

required_key: ""

upstreams:
  - name: opencode
    base_url: "https://opencode.ai/zen/v1"
    api_key: ""
    models:
      - big-pickle

  - name: openai
    base_url: "https://api.openai.com/v1"
    api_key: "sk-your-real-key"
    models:
      - gpt-4o
      - gpt-4o-mini

启动：

passkey-proxy
# passkey-proxy running on http://localhost:4000

配置参考

配置文件支持：passkey-proxy.yaml / passkey-proxy.yml / passkey-proxy.json / passkey-proxy.jsonc / config.yaml / config.yml / config.json，启动时自动查找。

全部字段

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | port | number | 4000 | 监听端口 | | level | string | "info" | 日志级别："info" 输出请求日志，"silent" 关闭请求日志 | | cors.enabled | boolean | true | 是否启用 CORS | | cors.origins | string | "*" | 允许的跨域来源 | | required_key | string | "" | 客户端认证密钥，为空则不校验 | | upstreams | array | — | 上游列表（见下方） |

upstreams 条目

| 字段 | 类型 | 说明 | |------|------|------| | name | string | 上游名称，仅用于日志标识 | | base_url | string | 上游 API 地址（如 https://api.openai.com/v1） | | api_key | string | 向上游发送的 API Key。空字符串则不传 Authorization 头 | | models | string[] | 属于该上游的 model 名称列表 |

使用

指定配置文件

passkey-proxy ./config/proxy.yaml

静默启动（日志写入文件）

passkey-proxy --silent
# 默认写入 passkey-proxy.log

passkey-proxy --silent --log-file /var/log/proxy.log
# 指定日志路径

设置客户端认证

required_key: "sk-my-secret"

客户端请求时必须携带：

Authorization: Bearer sk-my-secret

否则返回 401。

热重载

修改配置文件后自动加载，无需重启。热重载时会输出上游列表变化。

API 端点

GET /v1/models

返回所有上游配置的 model 列表。

POST /v1/chat/completions

转发聊天补全请求。按 model 字段自动路由到对应上游。

支持 stream: true 流式返回。

POST /v1/embeddings

转发 Embedding 请求。

GET /health

健康检查，返回 {"status":"ok"}。

与 opencode 集成

{
  "provider": {
    "big-pickle": {
      "id": "big-pickle",
      "options": {
        "apiKey": "sk-any-value",
        "baseURL": "http://localhost:4000/v1"
      },
      "models": { "big-pickle": { "id": "big-pickle" } }
    }
  },
  "model": "big-pickle/big-pickle"
}

客户端 apiKey 填任意非空值即可，passkey-proxy 会根据 upstream 配置决定传给上游什么 Key。