如何用 screenpipe CLI 启动本地录制并验证 localhost:3030 API 可用

如何用 screenpipe CLI 启动本地录制并验证 localhost:3030 API 可用【免费下载链接】screenpipeYC (S26) | Open Computer History | Record your screen continuously locally and provide context to your agents (Claude, Codex, Openclaw, Hermes, Runner...)项目地址: https://gitcode.com/GitHub_Trending/sc/screenpipe如果你只想用终端把 screenpipe 跑起来——不做桌面端安装、不接 AI 工具——目标是用一条npx命令启动本地录制然后确认localhost:3030上的 REST API 真的在响应并且已经能查到你刚录下的屏幕内容。这条路径适用于 macOSApple Silicon / Intel、Windows 10/11、Linux只需要 Node.js 环境命令通过npx拉取 CLI 及其平台二进制。录制数据全部存在本机的~/.screenpipe/目录。先确认平台受支持CLI 需要平台专用二进制只有darwin-arm64、darwin-x64、linux-x64、win32-x64四种组合受支持。如果命令失败先用这条命令看你的平台标识node -p process.platform - process.arch输出不在上述四种之内就是不支持的平台后续步骤无从谈起输出匹配则继续。启动录制主路径是前台进程适合交互式会话和排查问题npx -y screenpipelatest record这条命令启动 screenpipe 守护进程并持续录制屏幕数据写入~/.screenpipe/。latest保证每次都拉取最新发布的 CLI。两个可选分支每次运行record时 CLI 会每 5 分钟打印一条下载桌面应用的提醒。想静音的话加环境变量或预先导出SCREENPIPE_NO_REMINDERS1 npx -y screenpipelatest recordCLI 文档中给出的更完整的终端工作流是先进入一个干净的临时目录再执行命令避免bun x screenpipelatest与项目node_modules冲突见 screenpipe-cli SKILL。如果你是纯终端用户且需要开机自启、失败后自动重启可以改用服务模式service install默认就是录制模式屏幕 音频采集、本地索引、API开机/登录启动。service install --mode server是只服务已有数据、不录制的 API-only 模式不是本文的目标。验证 API 已启动health 端点不需要 tokenscreenpipe 启动后会在localhost:3030上提供 REST API。health 检查是文档指定的第一步验证且/health端点不需要认证见 API recipescurl http://localhost:3030/health如果这条请求失败说明本地 API 还没起来——不要继续往下查搜索先回到“CLI 起不来”一节排查。取得 API key 并验证搜索端点API 认证默认开启除/health外受保护端点都需要 key。文档给出的取 key 方式# 获取 API key 并存入环境变量 export SCREENPIPE_API_KEY$(npx -y screenpipelatest auth token)然后发起一次搜索请求验证 API 能返回数据curl http://localhost:3030/search?limit5content_typeall \ -H Authorization: Bearer $SCREENPIPE_API_KEY注意两点搜索端点是/search不是/api/search。对/api/search发请求会返回 404见 API reference 的告警和 troubleshooting。启动后立刻搜索可能返回空。文档明确说明捕获需要时间启动后等 1-2 分钟再重试这属于正常现象而不是故障。如果 key 没传对响应会是{error:unauthorized: API access requires authentication...}此时检查 bearer header 或改用文档给出的 query 参数方式?tokenkey文档标注此方式安全性较低。用 status 命令核对录制本身health 通过只说明 API 活着不代表屏幕流在采。CLI 提供status命令做更细的核对命令与输出含义见 screenpipe-cli SKILLnpx -y screenpipelatest status输出会区分几种状态recording normallyAPI 健康且至少一个采集流活跃、serving normally有意的 server 模式不采集、not capturing进程在但没有采集流、needs attention、stopped。它还打印屏幕/音频采集新鲜度、活跃设备、历史条数、总存储和 SQLite 文件路径。SKILL 文档特别提醒不要从进程 PID、端口占用或service status去推断“正在录制”——那只能证明进程存在不能证明有新数据进来。脚本化场景可用status --json重点看running、health.status、health.frame_status、health.audio_status、last_capture、last_audio_capture等字段running: true只代表 API 可用录制是否健康要看采集状态和时间戳。常见故障排查按 getting started 和 troubleshooting 给出的顺序处理record命令起不来平台不支持用上面的node -p命令确认输出是否落在四种支持组合内。缺少平台包运行npx -y screenpipelatest --version检查 CLI 能否解析出平台二进制重新用npx -y screenpipelatest拉取一次。macOS Gatekeeper 拦截出现 app is damaged 或 permission denied 时执行xattr -d com.apple.quarantine ~/.npm/_npx/*/node_modules/screenpipe*/bin/screenpipe该命令删除 npm 缓存中二进制上的隔离标记属于文档给出的修复方式也可以改用桌面应用它会自动处理权限。Linux 缺系统库sudo apt install libasound2-dev ffmpegUbuntu/Debian或sudo dnf install alsa-lib ffmpegFedora。这是需要 sudo 的系统包安装会改动系统环境按发行版二选一执行。Windows 缺 .NETinstaller 自带 .NET但纯 CLI 场景需要自行安装 .NET 8.0。端口 3030 已被占用screenpipe 已在运行时新的 CLI 实例无法绑定端口会失败。先查占用者macOS/Linux 用lsofWindows 用netstatlsof -i :3030 # macOS/Linux netstat -ano | findstr :3030 # Windowshealth 端点返回错误时文档建议的核对项确认屏幕录制权限已授予、重启应用、检查是否已有实例占着 3030 端口。health 正常但搜索没有结果等 1-2 分钟——screenpipe 需要时间捕获并处理帧先不带start_time、end_time、app_name、window_name等过滤参数做宽查询在content_typeaccessibility和content_typeall之间尝试再考虑收窄到ocr检查 included/ignored windows 过滤避免正在测试的应用被排除。需要更细的日志时可以在启动前设置SCREENPIPE_LOGdebugWindows PowerShell 下为$env:SCREENPIPE_LOG debug日志打印到终端级别有debug/info默认/warn也可按模块指定如SCREENPIPE_LOGscreenpipedebug,visiondebug见 API reference。限制与下一步只跑 CLI 不会得到桌面 timeline UI——record启动的是本地录制和 API视觉时间线、Pipes、设置界面属于桌面应用见 troubleshooting 中 “installed the CLI but cannot find the timeline” 一节。需要 UI 时另行安装桌面应用。确认localhost:3030可用之后完整的端点与参数/search的q、limit、content_type、start_time/end_time、app_name、browser_url等在 API reference 中可直接复制的工作流在 API recipes 中安装方式与更多选项见 getting started 和 quickstart。【免费下载链接】screenpipeYC (S26) | Open Computer History | Record your screen continuously locally and provide context to your agents (Claude, Codex, Openclaw, Hermes, Runner...)项目地址: https://gitcode.com/GitHub_Trending/sc/screenpipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考