连接后端

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

两类后端

• LLM 提供商——普通对话端点，覆盖市面上几乎所有服务：OpenAI、Anthropic、Ollama、Groq、LiteLLM、各种聚合网关。
• Hermes Agent——自带工具执行的自托管智能体：能搜索、跑命令、操作文件，是「能做事」的后端。内置在 browsa 里，填个地址就能用。
• OpenCode Agent——opencode 命令行智能体，自带官方无头服务器，同样内置：一条命令起服务，直连即用。
• Agent Bridge——本地 CLI 智能体桥（codex、claude、pi…）：独立守护进程把本机 CLI agent 变成统一协议后端，一张卡可同时连多个 agent。

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

配一张提供商卡

打开 ⚙ 设置 → LLM Providers。页面上预留了一张空的 LLM 1 卡，填完点 Save 即生效；也可以用 ＋ Add Provider 随时加卡：

保存后点 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" }
}

Agent Bridge

agent-bridge 是一个独立的小型本地守护进程：把 codex、claude、pi 等 CLI 智能体适配成统一的本地 HTTP 协议。ChatGPT Plus / Claude Pro 的订阅登录就能当模型来源——无需另购模型 API；pi 则用你在它内部配置好的模型供应商。

前提：本机装有 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；pi：npm i -g @earendil-works/pi-coding-agent pi-acp，首次运行 pi 配好模型供应商，要求 Node ≥ 22）。

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": "" }
     ]
   }

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 名字填上，状态里一并显示（如 ×3/3 healthy (codex, claude, pi)）；
6. 回到侧边栏，顶部下拉按「Agent Bridge · codex」逐个选择。每个 agent 有自己独立的会话线程，互不串线；中途切换时 browsa 会询问当前对话是带过去继续，还是新建会话从零开始。

不想手动执行 1–3 步？把下面这段整段复制给你的 CLI agent（设置页 Agent Bridge 卡上也有「复制配置提示词」按钮），让它替你完成安装、配置与启动，最后把它报告的桥地址填进第 4 步即可：

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

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. 完成后只报告最终的桥地址（http://127.0.0.1:端口），我会把它填进 browsa 设置页的 Agent Bridge 卡并点 Ping。

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

截图、粘贴图片与 PDF 图表会随消息发送给 agent（单条 ≤8 张）。三点提醒：审批卡需要该桥的 entry 配 "approval": "on-request"（默认 never 只会静默拒绝危险操作）；端口写在 agents.json 里，改端口后记得同步改 browsa 里那一行的地址；pi 的内置工具自动执行、通常不弹审批卡，也不上报 token 用量。

Ollama 本地模型

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