一扇通往
王座厅的窗。

说明：EmperorClaw 的界面为英文，下文中的按钮和菜单名称保留英文原文，并在首次出现时附上中文释义。

快速流程

1. 用一根 USB-C 数据线把开发板接到电脑上。
2. 在 Chrome 或 Edge 中打开 EmperorClaw，进入 Settings → Displays → Set up a display（设置 → 显示屏 → 设置显示屏），然后点击 Connect display（连接显示屏）。
3. 安装固件，选择你的 2.4 GHz Wi-Fi，点击 Finish setup（完成设置）。页面会显示 Your display is live（显示屏已上线）。

这就是全部步骤。拔下显示屏，用任意 USB 充电器供电即可。本指南的其余部分会介绍屏幕上显示的内容、你的数据如何受到保护，以及某一步失败时该怎么办。

准备清单

在浏览器中安装

1. 接线。用 USB-C 数据线把显示屏连接到电脑。
2. 连接。打开 Settings → Displays，然后在 Set up a display 下点击 Connect display。在浏览器的设备列表中选择这块开发板，它会显示为一个 USB JTAG/serial 设备。
3. 固件。页面会询问显示屏当前运行的版本。如果它已经是服务器所附带的版本，点击 Skip — already installed（跳过——已安装）。否则点击 Install firmware（安装固件），并保持数据线连接约一分钟。页面在写入之前会校验每个镜像的 SHA-256，显示屏已保存的设置也会保留。
4. Wi-Fi。显示屏会扫描周围网络，页面按信号强度从高到低列出它能看到的网络。选择你的网络并输入密码。如果网络名称是隐藏的，请使用 Other network（其他网络）。
5. 选项。为显示屏命名（默认为 “Desk display”），方便以后查找，并决定是否勾选 Include my private chats（包含我的私聊）。该选项默认关闭；详见隐私与安全。
6. 完成。点击 Finish setup。页面会为这块显示屏创建一个只读密钥，一次性把 Wi-Fi、服务器地址和密钥发送给开发板，然后等待。开发板重启、连上 Wi-Fi 并获取数据流。当它成功连上服务器时，页面会显示 Your display is live。

如果出了问题，页面会指出具体原因：Wi-Fi 密码被拒绝、找不到网络、连接 Wi-Fi 超时，或服务器拒绝了密钥。修正后点击 Try again（重试）。

你会看到什么

左右滑动切换模式。底部边缘的圆点表示当前所在的模式。每个智能体都是一个根据其 id 生成的 12×12 像素角色，所以同一个智能体看起来始终一样，身体颜色则取自该智能体自己的色相。

所有模式通用的信号

• 红色脉动边框：至少有一个智能体宕机。
• 金色脉动光环：有审批在等待人来处理。
• 右上角附近的状态点：绿色表示在线，金色表示正在连接或数据已过期，红色表示出错，紫色表示演示模式。
• 背光在 2 分钟内没有触摸或数据变化时会调暗，有触摸或数据变化时恢复。

光环和弧段中的健康颜色：绿色为健康，橙色为需要关注，红色为宕机，蓝色为空闲。在完成配置之前，显示屏会运行演示模式：模拟一家拥有七个智能体的公司，并带有一个小小的 DEMO 标签，这样你可以在接入任何服务器之前先检查硬件。

手势

隐私与安全

• 真正的只读。显示屏的密钥使用 Read only 范围。它只能调用 GET /api/mcp/live，别无其他：其他所有端点、MCP 服务器和实时 socket 都会以 403 拒绝它。只读密钥在 365 天后过期。
• 私聊需主动开启，且按密钥设置。勾选 Include my private chats 后，数据流会加入你自己与每个智能体的私聊往来：你写的消息以及智能体回复你的消息。其他成员的消息绝不会被发送。该选项在创建密钥时即已固定；如需更改，请吊销密钥并重新设置显示屏。
• 与你绑定。每个密钥都会记录是谁创建的。一旦此人离开公司，或不再是所有者或管理员，私聊会立即停止推送。
• 未开启该选项时，私聊永远不会出现在显示屏上。正在私聊中忙碌的智能体只会显示 “Working in a private chat”（正在私聊中工作）。
• 经过验证的 TLS。显示屏会依据标准的公共证书颁发机构，校验服务器证书链和主机名。普通的 http:// 只接受私有网络主机（10.x、172.16–31.x、192.168.x、*.local）。如果 EmperorClaw 本身是通过公网地址上的 http:// 打开的，浏览器设置会拒绝运行。
• 加锁的设置 Wi-Fi。设备端设置网络使用一个随机密码，它只显示在屏幕上，绝不会出现在串口日志中，因此只有能看到显示屏的人才能加入。已保存的密钥不会再次显示或打印。
• 令牌跟随服务器。如果更改了服务器地址却没有提供新令牌，已保存的令牌会被清除，因此令牌只会发送给创建它的那台服务器。

管理显示屏

Settings → Displays 会列出每一个显示屏密钥，包括名称、创建时间、最后使用时间以及是否开启了私聊。当某块显示屏离开你的桌面时，点击 Revoke（吊销），它会立即停止更新。要把显示屏迁移到另一个网络或服务器，重新运行一遍设置即可，新设置会替换已保存的设置。

故障排查

不用 Chrome 或 Edge

设备端设置门户

1. 在 EmperorClaw 中打开 Settings → Access Tokens（设置 → 访问令牌），创建一个 Read only 范围的令牌。只有在需要时才勾选 Include my private chats。复制该令牌。
2. 在显示屏上按住 5 秒。边缘会出现一圈逐渐填满的进度环，然后出现 SETUP 界面。
3. 用手机或笔记本电脑连接名为 EmperorClaw-Display 的 Wi-Fi 网络，密码显示在屏幕上。如果设置页面没有自动打开，请访问 http://192.168.4.1。
4. 选择你的 Wi-Fi，输入其密码、你的 EmperorClaw 地址（例如 https://emperor.example.com）以及令牌。轻点 Save and connect（保存并连接）。
5. 显示屏会重启。收到实时数据后，状态点会变成绿色。

设置会在 10 分钟后自动放弃，轻点屏幕也会取消设置。门户还提供 Run demo mode（运行演示模式）和 Erase settings（清除设置）。

串口控制台

在 115200 波特率下，显示屏接受 scan、status、version、ssid、pass、server、token、save 和 reset 等命令。开发者可以用 PlatformIO 从仓库中的 devices/throne-display/ 构建并烧录固件；固件 README（英文）记录了引脚映射、完整命令集以及内存设计。

面向开发者：实时数据流

显示屏只是第一个使用者。GET /api/mcp/live 会返回一份紧凑的 JSON 快照，概括你的整个 AI 团队，可用于你想构建的任何屏幕或仪表盘。在 Settings → Access Tokens 下创建一个 Read only 令牌（或调用 POST /api/settings/tokens 并传入 "scope": "read_only"），然后轮询它。

curl "https://emperorclaw.example.com/api/mcp/live?messages=8" \
  -H "Authorization: Bearer <read-only-token>" \
  -H 'If-None-Match: "<etag from the last response>"'

响应示例（只保留了一个智能体）：

{
  "v": 1,
  "ts": "2026-10-05T12:00:00.000Z",
  "company": { "name": "Acme" },
  "summary": { "agents": 6, "healthy": 4, "attention": 1, "down": 0, "idle": 1,
               "working": 2, "pendingApprovals": 1, "tasksInProgress": 5, "tasksOverdue": 0 },
  "agents": [
    { "id": "6f1c…", "name": "Ada Researcher", "short": "Ada", "hue": 212,
      "health": "healthy", "state": "typing",
      "activity": "Reading the Q3 report",
      "task": { "id": "9b2e…", "title": "Draft Q3 summary" },
      "lastSeenSec": 12, "unanswered": 0 }
  ],
  "messages": [
    { "id": "c41d…", "from": "Ada", "agentId": "6f1c…",
      "text": "Shipped the Q3 summary", "ageSec": 40 }
  ],
  "dm": []
}

轮询。每个响应都带有 ETag。在 If-None-Match 中回传它；如果没有变化，你会收到响应体为空的 304。ETag 会忽略时钟相关字段（ts、ageSec、lastSeenSec），因此收到 304 后，请自行把距上次 200 的时间累加到缓存值上。每个键始终存在，缺失的值为 null，而 v 只会在出现不兼容变更时改变。完整的接口约定见 API 参考（英文）。