niawjunior/aipass-bridge · 上手攻略

  • 仓库：niawjunior/aipass-bridge
  • 链接：https://github.com/niawjunior/aipass-bridge
  • 分类：ai · 工具桥接
  • 作者：spark
  • 更新：2026-09-03

是什么

aipass-bridge 是一个本地桥接工具：把泰国官方 AiPASS（aipass.go.th）面向泰国公民开放的 30+ 个 AI 模型（含文本、图像、视频、音乐生成）从原本只能网页聊天，扩展为终端、编辑器、以及任何 OpenAI 兼容工具都能调用的本地接口。它的关键设计是"凭据不出浏览器"——用一个 MV3 Chrome 扩展在你已登录的 AiPASS 标签页里发起真实请求，本地 Node 服务仅做协议转发，因此不会触及账号 Cookie，也不会绕过 AiPASS 的认证。

仓库对外宣传语是 "Make AiPASS great again — now with a terminal." 标语下面的副标题更直接：A terminal that speaks through a browser tab.

⚠️ 同名项目注意：搜 "aipass" 会出现两个无关项目——AIOSAI/AIPass（"Persistent Agent Workspace"，CLI 原生、Claude Code hooks、~/.aipass/ 配置，给任何项目加一层持久化 agent）和 aipass.ai（"AI agents that remember, collaborate"，同样是持久 agent 框架）。它们和本攻略的 niawjunior/aipass-bridge 完全无关，只是名字撞车，不要混淆。

解决什么问题

AiPASS 给泰国公民免费提供 GPT、Gemini、Claude、Llama、文心、豆包等 30+ 模型，按用量消耗统一的"credit pool"，但使用面只有一个 Web Chat：没有终端客户端、没有 OpenAI 兼容接口、不能直接喂给 Cursor / Continue / Cline / Aider 之类的 AI 编辑器，更不能读取本地文件做 agent 工作流。aipass-bridge 想填这块缺口：

  • 终端聊天 / 流式输出：把对话从网页搬到命令行，带 web search 与引用。
  • OpenAI 兼容协议：http://127.0.0.1:8787/v1 上跑 /chat/completions、/models、/images/generations，可用 openai Python/Node SDK、LiteLLM、Continue、Cline 等任意 base_url 工具接入。
  • 本地文件 agent：内置一个能读、搜、改本地文件的 agent，类似极简版 Cursor agent，跑在 --root <dir> 指向的项目里。
  • 图片 / 视频 / 音乐生成：自动枚举账户里所有 34 个模型（含图像、视频、音乐）按网页 UI 分组呈现，选一个就跑。
  • 额度可视化：弹出窗口和每次 agent 跑完都显示剩余 credit pool。

它适合"已经有 AiPASS 账号、想把它当主力 LLM 网关接到自己工具链"的开发者；不适合没有泰国 AiPASS 账号的人。

快速安装

环境前提：Node.js（仓库声明"无运行时依赖"+ MV3 Chrome 扩展；建议 Node 18+）+ 一台装 Chrome / Edge / Brave 等 Chromium 内核浏览器的机器 + 一个已登录的 AiPASS Web 标签页。

# 1. 取代码
git clone https://github.com/niawjunior/aipass-bridge.git
cd aipass-bridge

# 2. 安装依赖并起本地桥接（默认 127.0.0.1:8787）
npm install
npm run dev

# 3. 装 Chrome 扩展：浏览器打开 chrome://extensions
#    → 开启 "Developer mode"
#    → "Load unpacked" → 选 aipass-bridge/extension 目录
#    → 打开 https://de.aipass.net/chat 并保持登录
#    → 扩展弹窗应显示 "Connected"

如果 npm run dev 之后 Next.js app 也在跑 (npm run dev:next 是原脚手架遗留)，是正常的；桥接只关心 localhost:8787 端口。

快速体检：

npm run doctor
# ✓ bridge responding
# ✗ extension no tab attached
#  → open https://de.aipass.net/chat and leave it open
# – login skipped — nothing attached to ask

doctor 会顺次检查桥接服务 / 扩展 / 登录态 / 标签页，把第一个失败点指出来。

核心用法

# 普通聊天（带搜索和引用，输出流式）
npm run chat -- "ช่วยสรุปข่าว AI วันนี้"

# 指定图像模型生成图片
npm run chat -- "แมวน่ารัก" --model gpt-image-2

# 看所有可用模型（按网页 UI 分组）
npm run models

# 看账户剩余 credit
npm run credits

⚠️ 命令前必须有 --，否则参数会被 npm 自己吃掉。npm run chat --new 是 npm 的 flag，npm run chat -- --new 才是脚本自己的 flag。每个子命令都支持 --help。

本地文件 agent

# 让 agent 在当前目录下加一条 /health 路由（默认 dry run）
npm run agent -- "add a /health route" --root .

# 想真正写文件就显式 --apply
npm run agent -- "refactor src/foo.ts to use zod" --root . --apply

agent 的动作集合（读、搜索、改）写在 aipass-bridge/README.md 里的 "the agent's action set" 段，文档明确强调它能读、搜、改你 --root 指向的项目；dry run 模式下任何修改都会被回滚，跑前一定要确认 --root 没指错。

当作 OpenAI 兼容 API 用

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8787/v1",
    api_key="sk-dummy",  # 桥接不强校验，但仍要写
)

resp = client.chat.completions.create(
    model="gpt-5-mini",  # 实际可用名以 npm run models 为准
    messages=[{"role": "user", "content": "你好，介绍一下你自己。"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="")

任何 base_url 工具都能这样接入：Continue/Cline/Cursor 把 OpenAI provider 的 base URL 改成 http://127.0.0.1:8787/v1、API key 随便填；LiteLLM / OneAPI 等网关把它当上游源；LangChain / LlamaIndex 用 ChatOpenAI(base_url=...) 直接调。

无头部署（24×7 跑在一台服务器上）

仓库 aipass-bridge/deploy/README.md 提供 Docker + noVNC 部署方案——服务器上跑一个 headless Chromium 用 noVNC 暴露 VNC，扩展照常 attach 到那个无头浏览器，本地 8787 端口对局域网开放。注意：文档警告 "keep your bridge on localhost"——不要把它直接暴露到公网。

典型适用场景

  • 泰国本土独立开发者的主力 LLM 网关：已有 AiPASS 免费额度，想把多模型统一接进 IDE 和脚本。
  • 不想再分别买多家 API key 的小团队：30+ 模型通过 credit pool 统一计费，团队成员共享同一账号额度时比逐个订阅 GPT/Gemini/Claude 更便宜。
  • AI 写作 / 翻译 / 摘要工作流的本地化代理：用 npm run chat -- + 流式 + web search，把现有 shell pipeline（curl/jq/fzf）改造成 AI 增强版。
  • Cursor / Continue / Cline 等 IDE 工具的"免费替代 provider"：把 base_url 指向 8787 就能用 AiPASS 的付费模型做 AI 自动补全和 chat。
  • 本地 agent 实验场：内置 agent 给一个沙箱目录，跑 "重构这个项目 / 加这条路由 / 写这个测试" 之类的日常任务。

坑与注意

  1. 必须有泰国 AiPASS 账号：服务在泰国，认证 + 信用额度 + 标签页 URL 全部围绕 aipass.go.th 体系；非泰国 IP / 无账号直接跑不起来。文档默认登录 URL 是 https://de.aipass.net/chat，以你账号开通的实际域名为准。
  2. 凭据完全留在浏览器扩展里，但责任在你：仓库反复声明 "The bridge never sees it, and nothing is written to disk"，但前提是 Chrome 扩展 + 已登录标签页这条链路正常工作。一旦扩展被卸载或标签页被关，请求立刻失败。
  3. 34 个模型随时变动：README 里 "34 of them" 是当前抓取的口径，实际可用列表以 npm run models 输出为准；不同模型计费、速率限制、上下文窗口差异很大，不要硬编码到生产脚本里。
  4. agent 能改本地文件——务必先 dry run：npm run agent -- "..." --root . 不加 --apply 不会真正写入，但 --apply 一开就真改了。先在小目录跑通，再换大项目。
  5. 不要把 8787 端口暴露到公网：仓库反复强调 "keep your bridge on localhost"，因为任何能访问 127.0.0.1:8787 的人都等于在用你的 AiPASS 额度并能调出你的对话历史。Docker 部署务必配合防火墙 / SSH 隧道。
  6. Next.js 脚手架残留：npm run dev 会同时起桥接和遗留的 Next.js 应用（README 提到 npm run dev:next 仍可启动），如果你只想要桥接，看到额外端口不要惊慌。
  7. 版本与 Stars：抓取时搜索结果展示 44 stars / 37 forks（GitHub 实时数），选题榜标 104 stars 可能是数据口径或时间快照差异，以 GitHub 实时为准——不是仓库有问题。
  8. MIT 协议：LICENSE 显式 MIT，欢迎贡献，与贡献者同协议承担。需要做商业闭源分发前再读一遍 LICENSE 原文确认。

与同类对比

项目 定位 关键差异
niawjunior/aipass-bridge 把现成的 AiPASS 网页免费模型转成 OpenAI 兼容 API + 终端 + agent 凭据不出浏览器；34 个模型用 credit pool 统一计费；非泰国用户用不了
AIOSAI/AIPass / aipass.ai 持久化 agent workspace / CLI 原生 agent 框架 完全无关项目，名字撞车；目标是给本地项目加一层有记忆的 agent，不接外部 LLM 网关
LiteLLM 多 provider LLM 统一代理 需要各家 API key；不替你处理"已有网页免费账户"的场景
OneAPI 自部署 OpenAI 网关 同上，依赖各家付费 key；不解决"凭据留浏览器"的免费场景
继续用 AiPASS 网页 直接在 Web UI 聊天 无 CLI / 无 OpenAI 兼容 / 不能接入 IDE / 不能读本地文件

一句话区分：aipass-bridge 是"现成免费账户 → 任意 OpenAI 兼容工具"的桥；AIPass/AIOSAI 是"自己项目 → 持久 agent 框架"；LiteLLM/OneAPI 是"各家付费 key → 统一协议"。

一句话推荐结论

如果你已经是 AiPASS 用户、又不想只为终端和 IDE 各买一份 API key，aipass-bridge 是目前最干净的"借浏览器会话换 OpenAI 兼容接口"方案——前提是你愿意接受"必须留个 Chrome 标签页 + 默认 localhost + agent 真的能改文件"这三个代价。