使用指南
从安装到运行,完整的 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,访问 chrome://extensions
- 开启右上角 "开发者模式"
- 点击 "加载已解压的扩展程序"
- 选择项目中的 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 保存并连接
- 填写后点击页面底部的「保存设置」
- 选项页显示「连接状态:已连接」
- App 侧栏底部显示在线设备数,「今天」页显示「扩展已连接」
桌面 App 的端口可能顺延,扩展里的地址要跟着改;以「设置 → 服务状态」显示的 WebSocket 地址为准。
4. 配置 AI 模型
打开 App →「设置 → AI 模型」:
- 选择服务商预设(OpenAI / Anthropic / DeepSeek / Gemini / OpenRouter / Ollama / 自定义等),填写 API Key、Base URL 与模型名称;模型可用逗号分隔填写多个。
- 点击「测试模型连通性」确认可用后保存,新任务立即生效。
- 可在「提示词」调整分析与日报提示词,在「日报定时」开关早报和晚报。
没有配置 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)
常见问题
扩展无法连接服务器
- 确认 App 或后端服务已启动
- 检查 WebSocket 地址与端口:桌面 App 端口被占用时会顺延,以「设置 → 服务状态」为准
- 确认 API 密钥与服务端 CONNECT_ID 一致(默认 browser-tools)
- 检查防火墙是否放行端口
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 地址。