Setup Guide

使用指南

从安装到运行,完整的 Grabby 配置流程。

前置要求

  • - macOS 12+ / Windows 10+ / Linux — 桌面 App 运行环境
  • - Chrome 浏览器(或 Chromium 内核浏览器)— 运行扩展、采集真实网页
  • - Node.js 22+ — 仅从源码构建时需要(安装版无需)

1. 安装桌面 App

从 GitHub Releases 下载对应平台的安装包。它是单个自包含的可执行文件:Go 服务、HTTP / WebSocket / MCP、SQLite 数据库和桌面界面全部打包在一起,不需要再安装 Go、Node 或数据库。

下载最新版本

macOS

下载 Grabby-<版本>-macOS-universal.dmg,双击打开,把 Grabby 拖进 Applications。安装包未经过 Apple 公证:首次打开请在 Finder 中右键点击 Grabby →「打开」,或到「系统设置 → 隐私与安全性」点「仍要打开」。

Windows

下载 Grabby-<版本>-Windows-amd64-setup.exe(ARM 设备选 arm64)。SmartScreen 提示时点「更多信息 → 仍要运行」。也可以下载免安装 zip,解压后运行 Grabby.exe。

Linux

Debian / Ubuntu 使用 sudo apt install ./grabby_<版本>_amd64.deb;其他发行版解压 tar.gz 后运行 ./grabby,需要 GTK3 与 WebKitGTK 4.1。

首次启动

  • 内置服务自动监听 127.0.0.1:5040;端口被占用时自动顺延到 5041、5042…,实际端口见「设置 → 服务状态」。
  • 数据默认只保存在本机 SQLite:macOS 为 ~/Library/Application Support/Grabby,Windows 为 %AppData%\Grabby,Linux 为 ~/.config/Grabby。
  • 关闭窗口后 App 驻留托盘,服务继续运行;不需要终端,也不需要额外启动后端。

阅读体验

  • 卡片 / 列表两种展示方式,工具栏或快捷键 V 切换,选择会记住。
  • 点击文章在右侧打开应用内阅读面板,显示清洗后的全文、AI 精读、阅读进度与时长,不再跳出浏览器。
  • 阅读面板打开时,左侧列表自动进入 420px 紧凑模式,面板占满剩余宽度;窗口窄于 1120px 时切换为全宽覆盖。
  • 快捷键:Esc 关闭,J / K 下一篇 / 上一篇,/ 聚焦搜索;侧栏底部可直达浏览器插件、项目网站与 Releases。
  • 没抓取到正文的文章仍会显示摘要、AI 分析与来源,并提供「在浏览器打开」兜底。

从源码构建(可选)

需要 Go 1.27.3+;构建 Web 界面时需要 Node.js 22+。

git clone https://github.com/gusibi/grabby.git
cd grabby

make app            # 构建 → 打包 dist/Grabby.app → 启动
make run-desktop    # 前台运行,终端看日志

2. 安装浏览器扩展

方式一:Chrome 网上应用店(推荐)

一键安装,自动更新。

安装 Grabby 扩展

方式二:开发模式加载

如果你需要修改源码或进行开发调试:

  1. 打开 Chrome,访问 chrome://extensions
  2. 开启右上角 "开发者模式"
  3. 点击 "加载已解压的扩展程序"
  4. 选择项目中的 chrome-extension/ 目录(或 Release 里 grabby-extension-<版本>.zip 解压后的目录)

3. 配置并连接扩展

右键点击 Chrome 工具栏中的 Grabby 图标 →「选项」,填写连接信息:

字段 示例值 说明
WebSocket 服务器地址 ws://localhost:5040/ws_browser 与内置服务的监听端口一致
API 密钥 browser-tools 与服务端 CONNECT_ID 一致,默认 browser-tools
浏览器名称 chrome-office 多浏览器场景下的标识(可选),如 chrome-office
启动时自动连接 勾选 推荐开启,Chrome 启动后自动连回 App

认证原理

扩展把 API 密钥作为 conn_id 附加在 WebSocket URL 上,服务端校验它是否等于 CONNECT_ID,不一致则拒绝连接(403)。因此扩展里的 API 密钥必须与服务端的 CONNECT_ID 保持一致。

ws://localhost:5040/ws_browser?conn_id=browser-tools

保存并连接

  1. 填写后点击页面底部的「保存设置」
  2. 选项页显示「连接状态:已连接」
  3. App 侧栏底部显示在线设备数,「今天」页显示「扩展已连接」

桌面 App 的端口可能顺延,扩展里的地址要跟着改;以「设置 → 服务状态」显示的 WebSocket 地址为准。

4. 配置 AI 模型

打开 App →「设置 → AI 模型」:

  1. 选择服务商预设(OpenAI / Anthropic / DeepSeek / Gemini / OpenRouter / Ollama / 自定义等),填写 API Key、Base URL 与模型名称;模型可用逗号分隔填写多个。
  2. 点击「测试模型连通性」确认可用后保存,新任务立即生效。
  3. 可在「提示词」调整分析与日报提示词,在「日报定时」开关早报和晚报。

没有配置 AI 也能采集和阅读,只是不会有评分、分类与日报。

5. 只运行服务端(可选)

不启动桌面 App 时,也可以直接运行 Go 服务,通过浏览器使用 Web 管理界面,或把它当作纯 API / MCP 服务。两者共用同一套接口与 SQLite 数据。

cd go-server
cp .env.example .env
# 编辑 .env 按需修改配置

go run .
# 或编译后运行
go build -o go-server . && ./go-server

Web 管理界面:http://localhost:5040

环境变量

配置项 默认值 说明
HOST 0.0.0.0 服务器监听地址(桌面内嵌服务固定 127.0.0.1)
PORT 5040 服务器监听端口
CONNECT_ID browser-tools 扩展连接 ID,两端必须一致
DEFAULT_BROWSER (空) 多浏览器默认路由,留空使用第一个连接的浏览器
DEBUG false 调试模式,输出更多日志
WEBSOCKET_TIMEOUT 5.0 WebSocket 请求超时(秒)
API_EXTRACT_TIMEOUT 60.0 HTTP API extract 端点超时(秒)
GRABBY_ADMIN_KEY (空) Web 管理后台登录密钥,留空表示不需登录
GRABBY_API_TOKEN (空) API / MCP 访问 token,留空表示不鉴权
AI_ENABLED / AI_PROVIDER / AI_MODEL / AI_API_KEY / AI_BASE_URL / AI_QUALITY_THRESHOLD false / gemini / … AI 引擎配置,也可在 App 或 Web 设置页填写

配置优先级:系统环境变量 > .env 文件 > 代码默认值。桌面 App 内置服务不读取 .env 里的桌面专用变量。

服务启动后,控制台会输出可用端点:

HTTP API:
  POST http://localhost:5040/api/extract    - 提取网页 Markdown
  GET  http://localhost:5040/api/health     - 健康检查
  GET  http://localhost:5040/api/browsers   - 已连接浏览器列表

WebSocket:
  ws://localhost:5040/ws_browser  - 浏览器扩展连接

MCP Server:
  http://localhost:5040/mcp/sse

Go 后端支持交叉编译:

# macOS ARM64
GOOS=darwin GOARCH=arm64 go build -o go-server-darwin .

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o go-server-linux .

# Windows
GOOS=windows GOARCH=amd64 go build -o go-server.exe .

6. 验证安装

健康检查

curl http://localhost:5040/api/health

# 预期响应
{"status": "ok","browser_connected": true,"timestamp": "..."}

测试提取

curl -X POST http://localhost:5040/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# 预期响应
{"success": true,"url": "https://example.com","title": "Example Domain","markdown": "# Example Domain\n\n..."}

7. 配置 Claude Desktop

在 Claude Desktop 的配置文件中添加 Grabby MCP Server:

{
  "mcpServers": {
    "grabby": {
      "url": "http://localhost: 5040/mcp/sse"
    }
  }
}

配置文件位置:~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

常见问题

扩展无法连接服务器

  1. 确认 App 或后端服务已启动
  2. 检查 WebSocket 地址与端口:桌面 App 端口被占用时会顺延,以「设置 → 服务状态」为准
  3. 确认 API 密钥与服务端 CONNECT_ID 一致(默认 browser-tools)
  4. 检查防火墙是否放行端口

macOS 提示无法验证开发者

在 Finder 中右键点击 Grabby →「打开」;或到「系统设置 → 隐私与安全性」点「仍要打开」;也可以执行 xattr -dr com.apple.quarantine /Applications/Grabby.app。

Windows 提示已保护你的电脑

点「更多信息 → 仍要运行」。如果窗口空白,安装 Microsoft Edge WebView2 Runtime。

Go 编译失败

确保 Go 版本 >= 1.27.3。模块下载失败时设置代理:go env -w GOPROXY=https://goproxy.cn,direct

端口被占用

桌面 App 会自动顺延到 5041、5042…;手动运行的 Go 服务请修改 .env 中的 PORT,并同步修改扩展里的 WebSocket 地址。