OpenScreenShot

---

快速开始

npx openscreenshot shot https://example.com --out example.png --full

该命令会启动无头 Chrome，加载页面，保存整页 PNG，然后关闭浏览器。

**你需要：**Node.js 22.12 或更高版本，以及 Google Chrome、Chromium 或 Microsoft Edge。 软件包不附带浏览器，因此安装包体积较小。

包管理器	运行一次	全局安装
npm	npx openscreenshot shot <url>	npm i -g openscreenshot
pnpm	pnpm dlx openscreenshot shot <url>	pnpm add -g openscreenshot
Bun	bunx openscreenshot shot <url>	bun add -g openscreenshot

全局安装后，即可在任何位置使用 openscreenshot 命令。在 CI 中，请将它添加到项目中（npm i -D openscreenshot），这样每次运行都会使用 lockfile 中的版本。

CLI

openscreenshot shot <url> [--out <file>|-] [--full] [--width <n>] [--height <n>]
                    [--redact <selector>]... [--redact-pattern <name>]... [--redact-rect <x,y,w,h>]...
                    [--cloud [<base-url>]] [--key <api-key>] [--format <format>]
openscreenshot auth login [--cloud <base-url>]
openscreenshot auth logout
openscreenshot serve

选项	默认值	作用
<url>	必填	要截取的页面。请使用以 https:// 开头的完整 URL。
--out <file>	screenshot.png	PNG 的写入位置。使用 - 将字节写入标准输出。
--full	关闭	截取整个可滚动页面，而不只是视口。
--width <n>	1280	视口宽度，单位为像素，范围为 200 到 3840。
--height <n>	800	视口高度，单位为像素，范围为 200 到 2160。
--redact <selector>	无	遮盖与 CSS 选择器匹配的元素。可重复使用以添加更多元素。
--redact-pattern <name>	无	遮盖与 email、phone 或 secret 匹配的文本。可重复使用，也可用逗号分隔多个值。
--redact-rect <x,y,w,h>	无	遮盖矩形区域，坐标以输出图像的像素为单位。可重复使用以添加更多区域。
--cloud [<base-url>]	关闭	在 OpenScreenShot Cloud 上渲染。请参阅 Cloud。
--key <api-key>	无	本次运行使用的 Cloud API 密钥（osc_live_…）。
--format <format>	png	与 --cloud 搭配使用：png、jpeg、webp、pdf、html 或 markdown。

示例

# Full page
openscreenshot shot https://example.com --out page.png --full

# Fixed desktop viewport
openscreenshot shot https://example.com --out desktop.png --width 1440 --height 900

# Narrow viewport to check a responsive layout
openscreenshot shot https://example.com --out narrow.png --width 390 --height 844

# Pipe the PNG to another tool
openscreenshot shot https://example.com --out - > shot.png

# Cover the account menu, every email address, and a 200x40 area at the top left
openscreenshot shot https://example.com --out safe.png --redact "#account-menu" --redact-pattern email --redact-rect 0,0,200,40

有关工作原理及其可能遗漏的内容，请参阅脱敏。

本地输出始终为 PNG。.jpg 或 .pdf 文件名不会改变输出格式。要使用其他格式，请通过 --format 搭配 --cloud。

视口宽度较窄只会改变布局宽度。CLI 会保留桌面用户代理，因此不会模拟手机的触控输入或像素比。

退出代码

代码	含义
0	文件已写入。
1	截图失败，例如未找到 Chrome 或发生超时。
2	用法错误或选项超出范围。

退出代码 0 表示 CLI 已保存文件，但不能证明页面已正确加载，因此请查看图像，确认是否出现错误页面或加载动画。

MCP 服务

当通过管道传入 stdin 且不带参数时，openscreenshot 会通过 stdio 启动 Model Context Protocol 服务，MCP 客户端会以这种方式运行它。openscreenshot serve 的作用相同，并会继续使用现有配置。AI 客户端会将其作为本地进程启动；无需输入 URL。

添加到客户端

使用 mcpServers 对象的客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "openscreenshot": {
      "command": "npx",
      "args": ["-y", "openscreenshot"]
    }
  }
}

Claude Code：

claude mcp add openscreenshot -- npx -y openscreenshot

保存配置后，重启或重新加载客户端。客户端必须能在其 PATH 中找到 npx（或 pnpm、bunx）。

工具：capture_screenshot

输入	类型	默认值	说明
url	string	—	必填。完整页面 URL。
fullPage	boolean	false	截取整个页面。
width	integer	1280	200 至 3840。
height	integer	800	200 至 2160。
redact	object	—	可选。见下文。
cloud	boolean	false	在 Cloud 上渲染。参阅 Cloud。

{ "url": "https://example.com", "fullPage": true, "width": 1440, "height": 900 }

redact 包含三个可选列表：

字段	类型	作用范围
selectors	string[]	匹配每个 CSS 选择器的元素。
patterns	("email" | "phone" | "secret")[]	页面中的匹配文本及表单值。
rects	{ x, y, width, height }[]	矩形区域，单位为输出图像中的像素。

{
  "url": "https://example.com",
  "redact": {
    "selectors": ["#account-menu"],
    "patterns": ["email", "secret"],
    "rects": [{ "x": 0, "y": 0, "width": 200, "height": 40 }]
  }
}

该工具会将 PNG 作为 MCP 图像内容（image/png）返回，但不会写入文件。若要保存为指定文件名，请使用 CLI。

遮盖

遮盖会在页面中的目标上盖上黑色方框，然后截图。 未遮盖的像素不会进入 PNG，因此也不会传到你的 MCP 客户端或托管模型。

• 选择器。 方框会覆盖元素及其所有子元素。如果选择器未匹配到任何元素，或不是有效的 CSS，截图就会失败。
• 模式。 email 可查找电子邮件地址。phone 可查找包含 9 到 15 位数字的号码。secret 可查找常见的 API 密钥和令牌格式（OpenAI、Anthropic、Stripe、GitHub、AWS、Slack、Google、JWT）。它还会查找长度至少为 32 个字符、由字母、数字和下划线组成，且同时包含字母和数字的字符串，例如哈希值。 模式会检查文本，以及 input、textarea 和 select 字段的值。
• 矩形。 对于画布、图像和跨源 iframe 等选择器和模式无法检查的内容，请使用矩形。如果矩形完全位于图像之外，截图就会失败。

启用遮盖后，工具会暂停 CSS 动画、放置方框并截图。随后，它会再次查找目标。如果目标移出了方框，截图就会失败。截图失败时不会写入文件，也不会返回图像。

模式可能会漏掉文本。它们无法查找跨元素拆分的文本、绘制在画布或图像上的文本，也无法查找不认识的格式。它们还可能遮盖只是看起来匹配的文本。分享图像前请先检查。

可捕获和不可捕获的内容

每次截图都会启动一个全新的无头浏览器，并使用空白配置文件。

• 可以捕获已退出登录的访客能够看到的任何页面：公开网站、文档、状态页面、预发布构建，以及 localhost 开发服务器。
• 无法访问你的 Cookie 或已登录会话。登录页面后方的内容只会显示登录屏幕。
• 不会点击、输入、等待选择器或设置 Cookie。页面导航会等到网络空闲（networkidle2），最长等待 30 秒。

对于已登录页面、注释或 PDF 导出，请使用适用于 Chrome 和 Firefox 的 OpenScreenShot 浏览器扩展。

OpenScreenShot Cloud（可选）

OpenScreenShot Cloud 是托管截图 API。它会在 Cloud 服务上渲染页面，因此你无需在机器上安装 Chrome。本地模式仍为默认模式，且无需账户。

免费方案每月提供 100 次截图，无需绑定银行卡。截图失败不收费。付费方案请见定价页面。

登录

openscreenshot auth login

该命令会打印一个代码，例如 ABCD-EFGH，并在浏览器中打开 https://cloud.openscreenshot.app/device。使用 Cloud 发送到你邮箱的代码登录，然后批准该代码。随后，CLI 会将 API 密钥保存到 ~/.openscreenshot.json。要使用其他 Cloud 基础 URL，请添加 --cloud <url>。openscreenshot auth logout 会移除保存的密钥。

从 CLI 使用 Cloud

# Full-page PNG, rendered on Cloud
openscreenshot shot https://example.com --out page.png --full --cloud

# PDF of the page
openscreenshot shot https://example.com --out page.pdf --cloud --format pdf

--format 接受 png、jpeg、webp、pdf、html 和 markdown。--full、--width 和 --height 的用法与本地模式相同。

CLI 会使用它找到的第一个 API 密钥：

1. --key osc_live_…
2. OPENSCREENSHOT_API_KEY 环境变量
3. auth login 保存的密钥

基础 URL 的优先顺序为：--cloud <url>、OPENSCREENSHOT_CLOUD_URL，然后是 https://cloud.openscreenshot.app。

--redact、--redact-pattern 和 --redact-rect 可与 --cloud 配合使用。Cloud 服务会在返回图像前绘制黑色方框。遮盖需要输出 PNG。与本地模式一样，未匹配到任何内容的选择器会导致截图失败，且不会返回图像。

使用 MCP 调用 Cloud

在 capture_screenshot 上设置 cloud: true，即可在 Cloud 上渲染：

{ "url": "https://example.com", "fullPage": true, "cloud": true }

服务需要通过 openscreenshot auth login 获取密钥，或在服务的 env 块中设置 OPENSCREENSHOT_API_KEY。redact 在两种模式下都有效。

Cloud 还通过 Streamable HTTP 提供远程 MCP 端点，供仅接受远程 MCP URL 的客户端使用：

• URL：https://cloud.openscreenshot.app/mcp
• 请求头：Authorization: Bearer <api-key>
• 工具：capture_screenshot

Cloud 模式下的隐私

使用 --cloud 或 cloud: true 时，URL 和选项会发送到 OpenScreenShot Cloud，页面也会在 Cloud 服务器上渲染。请阅读 Cloud 隐私政策。 本地模式不会向 OpenScreenShot 发送任何内容。

Cloud API 文档列出了所有选项。

使用场景

• CI/CD： 每次部署时截取页面，用于发布说明、文档或视觉审查。 请参阅 CI 指南。
• DevOps： 通过 cron 或聊天命令，将仪表板和状态页面截取为快照，存入事件报告和运行手册。
• AI Agent： 让 Agent 查看刚刚构建或修改的页面。

故障排除

Chrome not found。 CLI 会检查 macOS、Linux 和 Windows 上的标准安装路径。如果浏览器安装在其他位置，请将 CHROME_PATH 设置为可执行文件的路径：

CHROME_PATH=/usr/bin/chromium openscreenshot shot https://example.com

在 Windows 上，为单个用户安装的 Chrome 位于 %LOCALAPPDATA% 下，且不会检测 Edge。请为两者设置 CHROME_PATH。在 MCP 客户端中，请在服务的 env 块中设置 CHROME_PATH。

脚本在不带参数运行 openscreenshot 时卡住。 不带参数且 stdin 有管道输入时，该命令会启动 MCP 服务并等待客户端连接。它会向 stderr 输出一行提示。要进行截图，请运行 openscreenshot shot <url>。

超时。 页面在 30 秒内未能停止加载。存在长轮询或流式连接的页面可能会出现这种情况。

图像空白或加载不完整。 有些页面会在网络请求停止后继续渲染。目前 CLI 尚无额外的等待选项。

隐私与安全

• 在本地模式下，所有操作都在你的机器上运行。该软件包不会发送遥测数据，也不会调用 OpenScreenShot 服务。只有在执行 auth login、使用 --cloud 或设置 cloud: true 时，才会调用 OpenScreenShot Cloud。
• 在 MCP 模式下，客户端会收到图像。如果客户端使用托管模型，可能会将图像发送给该模型的提供商。请使用 redact 在图像离开工具前遮盖数据。
• 无头浏览器以 --no-sandbox 运行，以便在容器和 CI 中使用。请仅截取你信任的 URL。

链接

• 源代码：mcp/ in PGHQdev/OpenScreenShot
• 浏览器扩展：Chrome Web Store · Firefox Add-ons
• 支持此项目：ko-fi.com/pghqdev

MIT © OpenScreenShot @PGHQdev