连接后端

browsa 没有账号、没有订阅、不加价——它只是把你自己的模型接口搬进侧边栏。 云端的、本地的、自建的，都行。

两类后端

按接入方式分两类——LLM 提供商是纯对话模型，Agent 提供商是能自己动手干活的智能体：

• LLM 提供商——普通对话端点，覆盖市面上几乎所有服务：OpenAI、Anthropic、Ollama、Groq、LiteLLM、各种聚合网关。
• Agent 提供商——自带工具执行的完整智能体后端：能搜索、跑命令、操作文件，是「能做事」的那一类。browsa 支持四种：
  • Hermes Agent——自托管智能体，内置在 browsa 里，填个地址就能用。
  • OpenCode Agent——opencode 命令行智能体，自带官方无头服务器，同样内置：一条命令起服务，直连即用。
  • OpenSquilla Agent——OpenSquilla 本地桌面智能体（网关 + 网页界面 + 桌面应用），省 token 的微内核设计、模型路由与技能系统；browsa 走它的网关 WebSocket，会话记忆在服务端。
  • Agent Bridge——本地智能体桥（codex、claude、pi、gemini、dsh…）：独立守护进程把本机 agent 变成统一协议后端，一张卡可同时连多个 agent。

切换到任一智能体时，browsa 会询问当前对话的去留——把对话记录作为第一条消息带给新 agent 接续上下文，或新建会话从零开始；每条回复都标注来自哪个 provider / agent。

配一张提供商卡

打开 ⚙ 设置 → LLM Providers。页面上预留了一张空的 LLM 1 卡，填完点 Save 即生效；之后每个服务商是卡头上一枚标签，点标签栏末尾的 ＋ 随时加卡：

保存后点 Ping：验证连通性并自动识别模型能力。第一个 Ping 通的提供商会自动设为当前使用；之后在侧边栏顶部下拉里随时切换，多模型的卡会按「别名 · 模型」逐个列出。

Hermes Agent

Hermes 是自托管 AI 智能体，带搜索、终端、文件、记忆等内置工具。browsa 用它的 /v1/runs 协议——比普通对话多出工具执行进度直播和危险操作审批卡（先批准，再执行）：

1. 安装：pip install hermes-agent（或按官方指引）；
2. 在 ~/.hermes/.env 里加 API_SERVER_ENABLED=true 和 API_SERVER_KEY=你的密钥；
3. 启动：hermes gateway，看到 API server listening on http://127.0.0.1:8642 即成功；
4. 在 browsa 设置里选中 Hermes Agent 卡，填 Base URL（如 http://127.0.0.1:8642）与 API Key，Ping 验证。

Hermes 卡固定存在、不可删除，只需 Base URL 和 Key——协议自动识别，服务端不支持 /v1/runs 时会自动回退到普通对话。

自建实例：让回答更快的服务端配置

Hermes 默认给 API 客户端挂载全量工具集——终端、浏览器、定时任务等十几组工具的定义会随每一轮请求重复发送（实测约 2.3 万 token），而浏览问答用不到其中大半；思考模式也默认全开，等待同样落在首字之前。在 ~/.hermes/config.yaml 里收紧这两项：

platform_toolsets:
  api_server:          # 只影响 API 客户端（browsa），Telegram 等通道不受影响
    - web              # 搜索、网页提取
    - vision           # 图片理解
    - clarify          # 反向提问
    - memory           # 跨会话记忆
agent:
  reasoning_overrides: # 按模型覆盖思考力度（全局项是 agent.reasoning_effort）
    你的模型名: medium

改完执行 hermes gateway restart 生效。作者实测（qwen3.8-flash、8 万 token 长上下文）：工具集瘦身让每轮请求少背约 1.4 万 token，思考降档直接缩短首字前的等待。另外模型服务普遍对 5 分钟内的连续追问做前缀缓存加速——连续提问比隔几分钟再问快得多，这是模型侧行为，无需任何配置。

OpenCode Agent

opencode 是开源命令行智能体，自带官方无头服务器——browsa 直连它即可（多轮上下文由 opencode 会话自己维护，browsa 只发送你的每一句话）。服务器在哪个目录启动，agent 就在哪个项目上干活：

1. 安装：npm i -g opencode-ai，首次运行按引导登录模型服务；
2. 启动：opencode serve --port 4096。建议固定端口——裸 opencode serve 会随机选端口且每次重启都变，固定后 browsa 里配置一次就不用再动；
3. 在 browsa 设置里选中 OpenCode Agent 卡，Base URL 填 http://127.0.0.1:4096（占位符即此建议值），Ping 验证。

当 opencode 要执行危险操作（如 shell 命令）时，审批卡会直接出现在 browsa 面板里。要启用这一步，在 ~/.config/opencode/opencode.json 里把权限设为询问：

{
  "permission": { "bash": "ask", "edit": "ask" }
}

OpenSquilla Agent

OpenSquilla 是本地智能体（网关 + 网页界面 + 桌面应用），主打省 token 的微内核设计、模型路由与技能系统。browsa 走它的网关 WebSocket（/ws）——与其自有网页界面同一条通道——因此拿到的是完整智能体体验：服务端会话记忆、流式增量、思考过程输出、服务端取消。browsa 的会话会以「browsa：…」的名字出现在应用的侧边栏里——之后随时打开桌面应用，就能从面板聊到一半的地方接着聊。

网关用桌面版或命令行二选一跑起来即可——browsa 对两者的接法完全一样，两条路线只有一处差别：网关读哪份配置文件（各自第 2 步）。改错文件是「配了却连不上」的最常见原因。

方式 A：桌面版（无需终端）

1. 安装并启动 OpenSquilla 桌面应用，v0.5.5 或更新（更旧的包内嵌的网关来源守卫不认扩展）。应用会自动拉起自己的网关——打开应用设置，记下它显示的网关地址（通常是 http://127.0.0.1:18791；自动取 18791–18830 里第一个空闲端口）。
2. 放行扩展——先找到桌面版实际读的配置文件（桌面版不读命令行网关的 ~/.opensquilla/config.toml，改错文件是「配了却连不上」的最常见原因）。最准的入口在应用自己这里：设置 → 高级 → 配置文件，它直接显示本机 config.toml 的完整路径（带一键复制），以它显示的为准。两个常见默认值：macOS 官方包 ~/Library/Application Support/OpenSquilla/opensquilla/config.toml；源码自建包 ~/Library/Application Support/@opensquilla/desktop-electron/opensquilla/config.toml（两套数据完全隔离）。路径里有空格，终端里必须转义：把整条路径包进引号，或给每个空格前加反斜杠——什么都不加，shell 会在空格处把路径截断（cd 直接报 No such file or directory，vim 会静默打开一个错误的空文件）：

   open -e "<粘贴 设置 → 高级 → 配置文件 里复制的完整路径>"   # 用 macOS「文本编辑」打开并修改
   cd ~/Library/Application\ Support/    # 不想加引号的进目录写法：空格前加反斜杠（Tab 补全也会自动加）

   文件不存在就新建一个纯文本文件，写入：

   [cors]
   allowed_origins = ["chrome-extension://kghjmmajnpbkljankbbjbmnhfdocaeho"]

3. 完全退出并重新打开应用（只关窗口不算）——网关只在启动时读一次配置。模型 / API key 在应用内配置（引导设置窗口），不读 shell 环境变量。进阶：桌面应用也能挂外部命令行网关——设 OPENSQUILLA_DESKTOP_GATEWAY_URL。
4. 跳到下方「配置 browsa」。

方式 B：命令行

1. 安装并启动网关（uv 提供 Python 3.12）：

   uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/opensquilla/opensquilla/releases/download/v0.5.5/opensquilla-0.5.5-py3-none-any.whl"
   opensquilla gateway start
   # → running: http://127.0.0.1:18791

2. 放行扩展——命令行网关读 ~/.opensquilla/config.toml，写入与方式 A 相同的 [cors] 块。网关的模型路由也在这份配置里设（见 OpenSquilla 自身文档；LLM key 通常随启动时的环境变量注入）。
3. 重启网关（Ctrl+C 停掉，再 opensquilla gateway start）——配置只在启动时读一次。
4. 跳到下方「配置 browsa」。

配置 browsa（两种方式相同）：在 browsa 设置里切到 OpenSquilla 标签，Base URL 填 ws://127.0.0.1:18791/ws（以网关实际显示的地址为准）；API Key 仅当网关配置了令牌时填写。点击 Ping 验证——会执行真实的 WebSocket 握手，绿色即同时证明连通性和来源白名单都已就绪。

这是 browsa 的扩展 ID（可在 chrome://extensions → browsa → ID 核对；解包加载填实际显示的值），逐字精确匹配（* 无效）。本地网关请用 ws://——wss 会被拒。

说明：每个 browsa 对话对应一个网关会话（清空 browsa 历史即重置）。聊天记录存放在网关侧——browsa 只转发你的文字，外加你刚附加过的页面（📎 上下文随下一条消息送出一次）；超大页面（超过 6 万字符）会作为 page-context.md 文档上传，由智能体用自己的工具分段阅读。粘贴的截图保留在 browsa 自己的历史里，暂不转发。

Agent Bridge

agent-bridge 是一个独立的小型本地守护进程：把 codex、claude、pi、gemini、dsh、zcode 等本地智能体适配成统一的本地 HTTP 协议。ChatGPT Plus / Claude Pro 的订阅登录就能当模型来源——无需另购模型 API；Gemini CLI 用 Google 账号登录（也支持 GEMINI_API_KEY）；pi 则用你在它内部配置好的模型供应商；dsh 用 DeepSeek API key，会话也会出现在 dsh 桌面端/Web 界面里；ZCode 走官方 CLI 的 headless 模式，沿用 ZCode 自己那份登录与模型配置。

前提：本机装有 Node.js 18+，以及要桥接的 agent CLI 并已登录（codex：npm i -g @openai/codex 后 codex login，用 ChatGPT 订阅账号即可；claude：npm i -g @anthropic-ai/claude-code 跑一次登录，再 npm i -g @agentclientprotocol/claude-agent-acp；gemini：npm i -g @google/gemini-cli 跑一次 gemini 登录 Google 账号（或设 GEMINI_API_KEY）；pi：npm i -g @earendil-works/pi-coding-agent pi-acp，首次运行 pi 配好模型供应商，要求 Node ≥ 22；dsh：装好 DeepSeek Harness——桌面版或 npm i -g @deepseek-ai/dsh——并存一次 DeepSeek API key：dsh-acp login，或在 dsh Web UI 的设置 → 模型里保存（openma 适配器 dsh-acp 已随 agent-bridge 内置）；zcode：装好 ZCode 桌面版并登录一次即可——桥会自动找到桌面版内置的 CLI，不需要额外配置或环境变量）。

1. 安装桥（已发布到 npm）：

   npm i -g @xiaohuzai/agent-bridge      # 或免安装试用：npx @xiaohuzai/agent-bridge serve

2. 准备配置——每座桥都是 agents.json 里的一个 entry（只起单个 agent 也是同样一条 entry），端口写在配置里：

   cp "$(npm root -g)/@xiaohuzai/agent-bridge/agents.example.json" agents.json
   chmod 600 agents.json

   {
     "bridges": [
       { "name": "codex",     "port": 3948, "apiKey": "",
         "sandbox": "workspace-write", "approval": "on-request" },
       { "name": "claude",    "port": 3949, "apiKey": "" },
       { "name": "pi",        "port": 3950, "apiKey": "" },
       { "name": "gemini",    "port": 3951, "apiKey": "" },
       { "name": "dsh",       "port": 3952, "apiKey": "" },
       { "name": "zcode",     "port": 3954, "apiKey": "", "mode": "edit" }
     ]
   }

3. 启动（在 agents.json 所在目录）：

   agent-bridge serve                                # 默认读 ./agents.json
   agent-bridge serve --config /path/to/agents.json  # 指定配置文件
   #  加 --bind 0.0.0.0 可暴露到本机之外（此时每个 entry 必须设 apiKey）

4. 在 browsa ⚙ 设置里选中 Agent Bridge 卡，点 ＋ 添加 Agent 逐行填桥地址（一行一个 agent，如 http://127.0.0.1:3948）。每行还可以填别名和该桥自己的 API Key——这里的 key 是桥自身的访问令牌（agents.json 里的 apiKey），不是模型服务的 key；仅本机使用时两边都留空；
5. 点 Ping——每个地址都会被探测；别名留空的行会自动用 /health 返回的 agent 名字填上，状态里一并显示（如 ×5/5 healthy (codex, claude, pi, gemini, dsh)）。每行有自己的状态点（灰=未测、绿=可连通、红=不通），行上的 ⟳ 可随时单独重测某一个 agent；
6. 回到侧边栏，顶部下拉按「Agent Bridge · codex」逐个选择，各自显示连通状态。每个 agent 有自己独立的会话线程，互不串线；中途切换时 browsa 会询问当前对话是带过去继续，还是新建会话从零开始。
7. agent 在工具调用前的过程自述（如 codex 宣告使用某技能）会折进步骤历史，不会混进回复正文。

不想手动执行 1–3 步？把下面这段整段复制给你的 CLI agent，让它替你完成安装、配置与启动，最后把它报告的桥地址填进上面第 4 步即可：

请在本机配置 agent-bridge 守护进程，让 browsa 浏览器扩展能通过本地 HTTP 调用你：

0. 先自检场景：你必须正运行在装着 browsa 浏览器扩展的这台电脑上（桥要和浏览器同机）。如果你在 SSH 会话、容器或另一台机器上，停下直接告诉我。
1. 全局安装（Node ≥ 18）：npm i -g @xiaohuzai/agent-bridge
2. 在固定工作目录创建 agents.json（条目形态以包内 agents.example.json 与 README 为准），为你自己加一个条目。如果你是 codex，保留 "approval": "on-request"（否则操作确认无法弹到 browsa）与 "sandbox": "workspace-write"：
   {"bridges":[{"name":"codex","port":3948,"apiKey":"","sandbox":"workspace-write","approval":"on-request"}]}
   其他 CLI agent（如 claude、pi）条目只需 name/port/apiKey。
3. 启动并验证：运行 agent-bridge serve（默认读 ./agents.json，前台驻留——验证要另开一条命令）：curl http://127.0.0.1:3948/health 应返回含你名字的 JSON。
4. 真回合冒烟（/health 只证明进程活着，不证明 agent 能跑通回合）：再另开一条命令发一个最小回合：
   curl -N -s -X POST http://127.0.0.1:3948/turns -H 'Content-Type: application/json' -d '{"text":"只回复两个字：就绪"}'
   这条 curl 会在回复完成后自己结束；期间流里应依次出现 start（带 sessionId）、delta、done。若出现 error 事件，把 message 原样发我。
5. 完成后只报告最终的桥地址（http://127.0.0.1:端口），我会把它填进 browsa 设置页的 Agent Bridge 卡并点 Ping。

任何一步失败就停下，把关键报错原样发给我，不要反复重试同一命令。

截图、粘贴图片与 PDF 图表会随消息发送给 agent（单条 ≤18 张，需 agent-bridge ≥0.8.0，旧版桥自动降级为前 8 张并在消息里注明）。端口写在 agents.json 里，改端口后记得同步改 browsa 里那一行的地址。

同为 Agent Bridge，各 agent 的行为并不完全一样——差异只有下面这几处，其余（安装、配置、Ping、切换会话）全部相同：

• codex：审批卡需要该 entry 配 "approval": "on-request"（默认 never 只会静默拒绝危险操作）。
• pi：内置工具自动执行，通常不弹审批卡，也不上报 token 用量。
• zcode（需 agent-bridge ≥0.12.0）：走官方 CLI 的 headless 模式，与上面几种有四点不同：
  • 没有审批卡：headless 回合里没人能点确认，CLI 自己 -p 的默认还是 yolo——所以 entry 的 "mode" 就是唯一的权限闸。默认 edit（自动应用改动）；只想问答设 plan（只读）；guarded 类似 yolo、只在 rm -rf / git reset --hard / force push 这类危险命令前停下（headless 下无人可批，表现为直接拒绝该命令）；build 会等审批而卡死，headless 下别用，yolo 全放开。
  • 模型由 ZCode 侧决定：providerOrder 第一家 provider 的 modelOrder 首项就是实际模型，桥不传也传不了。想换模型就改 ~/.zcode/v2/provider_config.json（改前关掉 ZCode——运行中的服务会用内存覆盖文件），并保持 modelOrder 与 personalModelIds 一致。账号订阅类 provider（比如登录了智谱 bigmodel 套餐）不会被 headless 自动选中，这时 zcode -p 会报 Select a model before sending a message；解法是加一个自定义供应商，或先在桌面版/CLI 里选好模型、再用会话 ID 续接（--resume 跳过模型解析，沿用该会话原来的模型）。每回合实际用哪个模型，桥会补发一条 note {kind:"model"}，以它为准。
  • 图片降级为文字：CLI 只接受本地文件的 --attach，桥不往磁盘写用户图片——截图与 PDF 图会以一句提示随消息发出，模型收不到像素。
  • 每回合一个新进程：新会话冷启动约 2–4 秒（PONG 回合实测 ~12.7 秒，带工具的回合 ~18.5 秒），每次都会带上 CLI 自己约 28K token 的系统提示；续接同一会话能命中 provider 前缀缓存。

zcode 的 CLI 定位顺序：entry 里的 command（非默认值时）> ZCODE_CLI 环境变量 > PATH 上的 zcode > 桌面版自带 CLI 自动发现（Linux 在 ~/.zcode/server/bin/zcode，macOS/Windows 在 app 的 resources/glm/zcode.cjs，用 app 自带运行时执行）。装好 ZCode 桌面版并登录一次，通常零配置就能跑通；文件在但 doctor 报找不到时，用前三种任一方式指过去。

Ollama 本地模型

本机跑 Ollama 的话，Base URL 填 http://localhost:11434，API 协议选 Chat Completions（Ollama 兼容 OpenAI 格式）。模型 ID 填已拉取的模型名，如 qwen3:32b。完全离线也能用。