刘天麒GitHub

PROJECT NOTES / PITTACUS RELAY

Pittacus Relay

真实 API Key 留在本机保险柜，AI 编程工具只拿一把本地通行证。

Pittacus Relay 是一个桌面端的 API Key 保险柜与本地模型网关：各家厂商的真实 Key 加密保存在应用里，Claude Code、opencode 这些 agent 工具拿到的只是一把只在本机有效、 随时可以更换的本地密钥，并且可以直接在工具自带的 /model 列表里切换不同厂商的模型。

当前公开版本为 v0.1.0，提供 Windows 与 macOS 安装包；安装包暂未代码签名， 首次打开会被系统拦截，需要手动放行。

Codex 接入和一组安全加固已经合并进 main，对应的 v0.1.1 Release 目前仍是草稿，还不能公开下载。

公开版本 v0.1.0 · v0.1.1 草稿 Codex 接入

OVERVIEW / 项目说明

Key 只交给保险柜，工具只拿通行证。

常见做法是把厂商 Key 直接写进 agent 工具的配置文件，于是它会出现在~/.claude/settings.json、环境变量和 agent 能读到的任何地方。配置被推到 GitHub、出现在截图里，或者 agent 被提示注入读取环境变量时，真实 Key 就跟着泄露了。

Pittacus Relay 反过来做：工具配置里只有本机网关地址和本地密钥，泄露出去也只能在你这台电脑的127.0.0.1 上使用，点一下“重新生成”就立即失效。它保护的是配置文件与 agent 环境这条泄露路径；同一系统账户下已经运行的恶意程序，仍然可能拿到本地密钥。

SYSTEM / 工作结构

网关、保险柜和工具接入各自守住一道边界。

本机网关127.0.0.1:17800
网关只监听本机回环地址，每个请求都必须携带本地密钥；请求的 Host 必须是回环地址，来自网页的跨站请求会被拒绝，用来防范 DNS rebinding。
API Key 保险柜safeStorage · DPAPI / Keychain
厂商 Key 先经系统密钥存储加密再落盘，界面进程看不到明文；只在网关转发请求的那一刻写进发往厂商的 https 请求头，不进入任何工具配置，也不进入请求日志。
工具接入Claude Code / opencode
一键把网关地址和本地密钥写进工具配置，写入前记录原值，“还原”只撤销 Pittacus Relay 写入的字段；增删模型、改端口或重新生成密钥时，已接入的工具会自动同步。
模型路由provider-id/model
按模型名把请求路由到对应厂商，例如 kimi/kimi-k2；工具请求了不认识的模型时回落到“轻量模型 / 主模型”设置。Anthropic 与 Chat Completions 请求直接转发到厂商自己的兼容端点，不做格式互转。
Codex 协议转换/v1/responses → /chat/completions
Codex 只使用 OpenAI Responses API，而许多厂商只提供 Chat Completions；网关会把请求转换过去，再把流式回复（文本、工具调用、思考内容）转换回 Responses 事件。这部分已合并进 main，随 v0.1.1 发布，目前 v0.1.1 仍是草稿。
用量统计usage.json · 保留 90 天
按天、按模型汇总请求数、输入输出 token 与缓存命中，数据来自厂商响应中的 usage 字段；只记录摘要与计数，不记录对话内容，也没有遥测。
桌面应用Electron + React · Windows / macOS
常驻系统托盘或菜单栏，关闭窗口不会停止网关；提供 Windows x64 / ARM 与 macOS Apple 芯片 / Intel 四种安装包，界面支持简体中文与英文。

PROGRESS / 公开进度

进度记录

每条内容保留日期

  1. 重写 README

    重新组织 README：先讲清楚要解决的问题与做法，再把快速开始、功能列表和下载入口前置，方便第一次打开仓库的人更快判断是否适合自己。本次只涉及文档；v0.1.1 Release 仍是草稿，公开下载的最新版本仍是 v0.1.0。

    查看对应提交

  2. README 改为双语版本并加入演示动图

    README 以英文为主版本，并补齐完整的简体中文版；首屏加入演示动图：接入 Claude Code、确认 settings.json 里只有本地密钥，再在 /model 列表里切换模型。

    查看对应提交

  3. 加入 Codex 接入并加固 Key 保护（v0.1.1 草稿）

    新增 Codex 接入：一键写入 ~/.codex/config.toml，按行编辑以保留注释与其他配置，只提供 Chat Completions 的厂商由网关转换 Responses 请求后转发。同时加固安全：首次设置 PIN 需要 Windows Hello / Touch ID 确认，Claude Code 原有 Key 改为加密备份，修改供应商地址必须重新填写 Key。代码已合并进 main，但 v0.1.1 Release 仍是草稿，公开下载的最新版本仍是 v0.1.0。

    查看对应提交

  4. 准备 Windows 代码签名

    接入 SignPath Foundation 面向开源项目的免费代码签名流程，CI 配置放在 .signpath/ 目录；项目申请仍在等待批准，批准前发布的安装包仍未签名。

    查看对应提交

  5. 发布 v0.1.0 初始版本

    首个公开版本：在本机起网关，提供一个地址加一把本地密钥，一键写入 Claude Code 与 opencode 配置，在工具自带的 /model 列表里切换各厂商模型；Windows 与 macOS 安装包随 Release 发布，并附 SHA-256 校验值。

    查看对应提交

STATUS / 当前状态

已完成与计划中

已完成

  • 本机网关与随时可重新生成的本地密钥
  • 厂商 Key 经系统密钥存储加密保存
  • Claude Code 与 opencode 一键接入与还原
  • 在工具自带的 /model 列表里切换模型
  • 按天、按模型的 API 用量统计
  • Windows / macOS 安装包（v0.1.0 已发布）

计划中

  • Codex 接入（已合并 main，v0.1.1 草稿待发布）
  • Windows 代码签名（SignPath Foundation 申请中）
  • macOS 签名与公证，去掉首次打开时的系统拦截
  • 自动更新
  • OpenAI ↔ Anthropic 协议转换
  • 鸿蒙 PC 版（设想，尚未排期）
查看 GitHub 源码 返回个人主页