---
title: Capture（屏幕捕获）
description: 将每位成员的屏幕、输入操作和音频全天候（24/7）录制到属于 OpenChatly 账户的可搜索时间线中。
---

OpenChatly Capture 会全天候录制成员自己的计算机，以便您可以查找和回放屏幕上发生的任何事件。它录制三个层面的内容：

- **屏幕**：视频、应用程序、窗口标题、URL 以及屏幕上的文字；
- **输入操作**（点击、打字），每次操作均附带一张截图；
- **音频**及文字转录，当账户策略开启此功能时生效。

OpenChatly 会上传这些录制内容，将其按人员索引到一条时间线中，并允许您回放和搜索任何时刻。

Capture 归属于 OpenChatly 账户（即您的组织），而非某个具体项目。一个账户对应一个 Capture 工作区：包含一个开关和一套策略。每台计算机均需登录到该账户。

## 开启 Capture

拥有 `capture.manage` 权限的人员可为账户开启 Capture。账户所有者和管理员默认拥有此权限。Capture 默认处于关闭状态。在关闭期间：

- 所有 Capture 路由均返回 `403` 错误，错误代码为 `code: "capture_disabled"`；
- 设备无法登录或获取存储凭证；
- OpenChatly 不会索引任何新内容。

OpenChatly Capture 在 `/capture` 路径下拥有独立的管理区域。通过命令面板（Command Palette）打开 **OpenChatly Capture**（或直接访问 `/capture`），选择 **Settings**（设置），然后为组织开启 **OpenChatly Capture**。同一页面还包含组织的规则配置：哪些计算机进行录制、OpenChatly 保留数据多长时间、数据存储位置、全账户暂停开关以及可选的通知设置。该区域还包含 **Devices**（设备）和 **Timeline**（时间线）。

通过 API 开启：向 `PATCH /v1/accounts/<account_id>/capture` 发送 `{"enabled": true}`。
通过 TypeScript 开启：`kortix.capture.account(accountId).workspace.setEnabled(true)`。

## 安装 OpenChatly Capture

OpenChatly Capture 是一款独立应用，与 OpenChatly 主应用分开安装。它在 Windows、macOS 和 Linux 上后台运行，在通知区域（macOS 上为菜单栏）显示图标，并录制内容到一个 OpenChatly 账户中。计算机可通过以下两种方式之一进行连接：

| 方式 | 适用场景 | 操作方法 |
|---|---|---|
| 使用 OpenChatly 登录 | 个人在自己的计算机上操作 | 用户在浏览器中批准该计算机 |
| 注册令牌（Enrollment token） | IT 部门批量部署多台计算机 | IT 使用令牌进行安装；无需用户登录。请参阅 [IT 部署指南](/docs/zh/capture/rollout) |

下载对应计算机的安装程序：[Windows](/download/capture/windows) (`.msi`)、[macOS](/download/capture/macos) (`.pkg`) 或 [Linux](/download/capture/linux) (`.deb`)。这些链接也可在 **Devices**（设备）页面的 **Get OpenChatly Capture** 下找到。

安装程序随每个 OpenChatly 版本一同发布，版本号相同，旁边附有 `CAPTURE-SHA256SUMS` 校验和文件。如需更新，直接使用新版安装程序覆盖旧版即可，原有配置将保留。

使用 OpenChatly 登录的步骤：

1. 安装 OpenChatly Capture，并通过 OpenChatly Capture 图标打开应用。
2. 选择 **Sign in with OpenChatly…**（使用 OpenChatly 登录…）。浏览器会打开带有代码的 `/capture/authorize` 页面。请核对代码是否匹配，然后选择账户。仅列出已开启 Capture 的账户。
3. 在 macOS 上，系统提示时请授予相应权限：屏幕录制（Screen Recording）、辅助功能和输入监控（Accessibility and Input Monitoring，用于记录操作）、麦克风（Microphone，用于录音）。Windows 和 Linux 无需授予额外权限。

如果没有显示图标，可运行命令：
`kortix-capture sync setup --provider kortix --issuer <your OpenChatly API>`。

随后，计算机会以您的身份向该账户录制内容并上传每个已完成的条目。它会获得一个可撤销的设备令牌，并由此获取用于其专属文件夹（`orgs/<account_id>/<device_id>/`）的短期存储凭证，以及对策略的读取权限。在同一台计算机上重新登录会复用该设备。在设备上清除某个时间段的数据也会将其从 OpenChatly 中移除。

## 将计算机关联到个人

每台计算机在 **Devices**（设备）列表中均显示为一个设备。列表展示了每台设备的状态（**Recording**（录制中）、**Paused**（已暂停）、**Offline**（离线）、**Needs permission**（需要权限）等）、上次录制时间以及设备群组的摘要。当计算机停止录制及恢复正常时，OpenChatly 会向管理 Capture 的人员发送通知。

您亲自登录的计算机将为您录制。IT 使用个人令牌注册的计算机将为该令牌指定的成员录制。IT 使用企业令牌注册的计算机将为账户录制，且**不关联任何人**。这是一种正常状态：仅当您希望其出现在某人的时间线中时，才将其关联到具体人员。

若要关联设备，请在该设备上选择 **Link to a person…**（关联到个人…）；若要更改关联人员，请选择 **Change linked person…**（更改关联个人）（需具备 `capture.manage` 权限）。此后，该计算机将为该人员录制。之前未关联任何人时录制的内容会在几分钟内转移至该人员名下；之前为其他人员录制的内容仍归原主所有。

通过 API 关联：向 `PUT /v1/accounts/<account_id>/capture/devices/<device_id>/link` 发送 `{"user_id": "<member>"}`，或发送 `{"user_id": null}` 以取消关联。

只有具备 `capture.read_all` 权限的人员才能看到未关联任何人的计算机。每次读取此类计算机都会在审计日志中写入 `capture.device_view` 记录。Agent 永远不会读取此类计算机。

## 权限可见性（Who sees what）

访问权限由 OpenChatly IAM（身份与访问管理）控制。Capture 没有自己的独立角色。

| 角色 | 读取权限 | 写入权限 |
|---|---|---|
| 每位成员 | 自己的设备和时间线 | 撤销自己的设备 |
| `capture.read_all` | 所有成员的设备与时间线，以及全账户搜索 | 无 |
| `capture.manage` | 工作区和策略 | 开关、策略、撤销任意设备 |
| Agent | 仅限其私有会话所代表的个人的时间线 | 无 |

账户所有者和管理员默认拥有 `capture.read_all` 和 `capture.manage` 权限。若要将其中任一权限授予他人，请将其添加到自定义角色中（**Account** → **Roles**）。OpenChatly API 密钥的行为等同于创建该密钥的人员，拥有相同的权限。

每次读取其他成员的数据都会在账户审计日志中写入 `capture.member_view`。全账户读取（所有设备、账户搜索）会写入 `capture.account_view`。Agent 的读取会写入 `capture.agent_read`。开启或关闭 Capture 会分别写入 `capture.enable` 或 `capture.disable`。

## 策略（The policy）

一套策略适用于账户下的每台设备：

- **录制层级**：屏幕、操作、音频（音频默认关闭，需手动开启）；
- **应用与网站**：选择策略类型，然后配置其列表。
  - **排除策略**（默认）：录制除排除项以外的所有内容：包括应用、网站、类别（密码管理器、即时通讯、银行类；点击 **Show list** 可查看类别涵盖的所有应用和网站）以及隐私浏览窗口。
  - **包含策略**：仅录制您包含的应用和网站。被包含的应用会被完整录制；被包含的网站在任何浏览器中均会被录制。其他所有内容均会被黑屏遮挡。排除项仍作为**永不录制（即使已包含）**生效。
  - **允许成员添加自己的包含应用和网站**（默认开启）。关闭此选项后，计算机仅录制您的“包含列表”。成员始终可以添加要跳过的应用和网站，因为这只会减少录制内容。
  - **常用应用**和**常用网站**支持一键添加；添加应用时会同时加入其 macOS 和 Windows 标识符，并按名称显示。
  - 任何被跳过的内容都会被黑屏遮挡，当显示器没有剩余可录制内容时不会写入任何帧，且在跳过的应用中的操作不会被录制。成员可以在 OpenChatly Capture 中（Settings → Apps and websites）添加自己的条目，但无法移除组织设置的条目，也无法将包含策略切换回排除策略。音频不按应用过滤：在包含策略下请保持音频层级关闭；
- **全账户暂停**；
- **屏幕帧**：每 0.5 到 10 秒捕获一帧，以及分辨率（720p 到 4K）。若保留为 **Each computer decides**（由每台计算机决定），计算机会使用其自身设置（每 2 秒一帧，1440p）。若手动设置，每台计算机都会使用该设置并显示为已锁定。点击、打字和滚动操作会以各自的截图按任意间隔进行录制；当屏幕在没有输入的情况下快速变化时（例如实时仪表盘），建议选择 1 秒间隔；
- **保留期限**：**In OpenChatly**（在 OpenChatly 中）表示 OpenChatly 保留录制内容的天数（`remote_days`，默认 90 天，设为 `0` 则无限期保留），**On the computer**（在计算机上）表示计算机在上传后保留本地副本的小时数（`local_hours`，默认 0 小时）；
- **可选通知**：每人会看到一次，且在通知文本更改时会再次看到；
- **Experimental → Privacy controls**（实验性 → 隐私控制，默认关闭）：在计算机上显示个人数据掩码功能（每台计算机首次使用时需下载约 1 GB 的模型）。关闭此开关会隐藏该功能；已设置的掩码规则将继续生效。

保留期限是一个上限：成员可以在自己的计算机上保留录制内容的时间短于策略允许的时间，但不能长于策略允许的时间。默认情况下，计算机会保留尚未上传的录制内容，并在上传 7 天后删除已上传的内容。

计算机在登录或被 IT 注册时会立即获取策略，因此新计算机启动时会自动应用您的排除或包含策略，无需进行任何设置。在策略到达之前（登录后数秒内），计算机不会录制任何内容。在 OpenChatly Capture 的 Settings → Apps and websites 中，会显示其规则来源：若同步自组织，会显示 "Synced from"（同步自）及策略类型；若未同步到组织，则显示 "Set on this computer"（在本机设置）。

OpenChatly 会将策略发布到捕获存储中的 `orgs/<account_id>/policy.json`，每台设备会在一分钟内读取该策略。设备无法写入自己的策略。OpenChatly 还会在索引时强制执行层级限制：设备永远无法扩大策略范围。

设备会录制每个已连接的显示器，优先录制活动显示器（即拥有焦点窗口的显示器）。每个显示器都是独立的录制项；时间线会标明每个条目和帧所属的显示器。

## 录制内容的存储位置

默认情况下，OpenChatly 会保留并索引录制内容（**OpenChatly 托管**）。在 **Settings** → **Storage** 下，所有者或管理员可以将账户指向其拥有的 S3 存储桶：AWS S3，或 MinIO 等兼容 S3 的存储。OpenChatly 会在该存储桶中读取、索引并为录制内容签名。

| 字段 | 含义 |
|---|---|
| **Endpoint**（端点） | 若使用 AWS 请留空。若使用其他兼容 S3 的存储，请填写完整 URL。 |
| **Region**（区域）、**Bucket**（存储桶） | 存储桶的位置和名称。 |
| **Path-style URLs**（路径样式 URL） | MinIO 和大多数自托管存储需开启；AWS 需关闭。 |
| **Access**（访问权限） | OpenChatly 扮演的 **IAM role (STS)**（推荐：每台计算机获取其专属文件夹的凭证），或静态的 **Access key**（访问密钥）对（每台计算机获得对整个存储桶的账户级访问权限）。 |

在保存选择之前，OpenChatly 会写入一个测试对象。切换存储位置不会移动已存储的录制内容。计算机上的客户端加密与索引功能不兼容：计算机加密的录制内容无法在 OpenChatly 中进行搜索或播放。通过 API 操作：`GET` 和 `PUT /v1/accounts/<account_id>/capture/storage`（需 `capture.manage` 权限）。在自托管 OpenChatly 上，请参阅[自托管指南](/docs/zh/developers#自托管self-hosting)。

## OpenChatly Capture API

Capture 录制的所有内容均可通过 OpenChatly API 密钥读取，支持从脚本、Notebook、BI 工具或 Agent 进行访问。

**身份验证（Auth）。** 在 OpenChatly 中创建密钥（**Settings** → **Personal access keys**，或在 **Devices** 页面的 **OpenChatly Capture API** 对话框中选择 **Create an API key**），或通过 `POST /v1/accounts/tokens` 创建。发送请求时，请将其作为 `Authorization: Bearer kortix_pat_…` 传递。

**基础 URL（Base URL）。** `https://<your OpenChatly API>/v1/accounts/<account_id>/capture`。
`GET /v1/accounts` 可列出您的账户。

**作用域（Scoping）。** 默认情况下，每个路由仅读取您自己的数据。若具备 `capture.read_all` 权限，可传递 `user_id=<member>`（审计记录为 `capture.member_view`）；或在路由支持的情况下传递 `scope=account` 以读取所有成员的数据（审计记录为 `capture.account_view`）。未关联任何人的设备通过其 `device_id` 读取，无需 `user_id`（需具备 `capture.read_all` 权限，审计记录为 `capture.device_view`）；若无此权限，同一请求仅返回该设备的您自己的数据行。超出权限范围的读取请求将返回 `403 capture_forbidden`。当 Capture 处于关闭状态时，所有路由均返回 `403 capture_disabled`。

| 端点（Endpoint） | 返回值（Returns） |
|---|---|
| `GET /` | `{ account_id, enabled, can_read_all, can_manage, updated_at }` |
| `PATCH /` `{ "enabled": true }` | 同上；需 `capture.manage` 权限 |
| `GET enrollment-tokens` · `POST enrollment-tokens` · `DELETE enrollment-tokens/<token_id>` | IT 部署令牌；需 `capture.manage` 权限（参见 [IT 部署指南](/docs/zh/capture/rollout)） |
| `GET enrollments?status=pending` · `POST enrollments/<id>/approve` `{ "user_id" }` · `POST enrollments/<id>/deny` | 等待审批的计算机；需 `capture.manage` 权限 |
| `PUT devices/<device_id>/link` `{ "user_id" }` | 将设备关联到成员，或传递 `null` 以取消关联；需 `capture.manage` 权限 |
| `POST devices/<device_id>/sync` | 立即读取设备状态和索引，并将新条目加入索引队列 |
| `GET storage` · `PUT storage` | 账户存储录制内容的位置；需 `capture.manage` 权限；密钥永远不会被返回 |
| `GET devices?user_id=&scope=account` | 设备及其实时状态：设备最后报告的状态（例如 `recording`（录制中）、`paused`（已暂停）），或在静默 2 分钟后显示为 `offline`（离线） |
| `DELETE devices/<device_id>` | 撤销设备：其令牌立即失效 |
| `GET devices/<device_id>/assets/<name>` | 某个操作截图的签名 URL（有效期 5 分钟） |
| `GET policy` · `PUT policy` `{ "policy": { … } }` | 账户策略；写入需 `capture.manage` 权限 |
| `GET days?tz=Europe/Berlin&user_id=&device_id=` | 包含录制内容的日期（按时间倒序），按指定时区排列 |
| `GET timeline?day=&from=&to=&user_id=&device_id=&display_id=` | `{ displays, focus, runs, chunks }`：可见的显示器、焦点所在显示器及时间、应用和窗口运行记录（针对焦点显示器或 `display_id` 指定的显示器），以及最多 31 天窗口内的索引条目 |
| `GET timeline/items?from=&to=&user_id=&device_id=&display_id=` | `{ frames, actions, audio }`，按时间正序排列，每类最多 500 条；传递 `display_id=all` 可获取所有显示器的数据 |
| `GET search?q=refund or invoice&kinds=screen,actions,audio&app=&from=&to=&limit=20&scope=account` | 命中结果（按时间倒序）：`{ kind, id, ts, user_id, device_id, chunk_id, display_id, display_name, app, title, url, snippet }`（每个块和窗口对应一个屏幕命中项；`limit` 最大为 100） |
| `GET frames/<frame_id>` | `{ frame, video: { url, expires_at, offset_ms }, screenshot }`：完整的屏幕文字、用于跳转的 1 fps 块视频、最近的操作截图（均为签名 URL，有效期 5 分钟） |
| `GET chunks/<chunk_id>/media` | 某条目视频或音频的签名 URL |

`user_id` 会通过 `GET /v1/accounts/<account_id>/members` 解析为姓名和邮箱，账户中的每位成员均可读取此接口。

示例：

```bash
curl -s -H "Authorization: Bearer  $ KORTIX_API_KEY" \
  "https://<your OpenChatly API>/v1/accounts/ $ ACCOUNT/capture/search?q=invoice&limit=5"
```

TypeScript SDK 封装了相同的路由：`kortix.capture.account(accountId)`（参见 [SDK 参考 > `kortix.capture`](/docs/zh/developers#kortixcapture)）。

## 会话中的 Agent

成员私有会话中的 Agent 通过 `/v1/capture/me/search`、`/v1/capture/me/timeline` 和 `/v1/capture/me/frames/<frame_id>` 接口，或使用 `kortix capture search`、`timeline` 和 `frame` 命令来读取该成员的时间线。它仅能在会话所属的账户中读取该人员的数据。触发器运行（trigger run）或共享会话不代表任何个人，因此会收到 `403 capture_no_human` 错误。

## 基于此进行开发

客户端接口和 React Hooks 的详细信息，请参阅 [SDK 参考 > `kortix.capture`](/docs/zh/developers#kortixcapture)。
