自托管服务器¶

自托管服务器是在您自己的无屏幕计算机（VPS、家用服务器或云 VM）上运行的 Linux OpenBot 构建。它是您账户中的普通远程主机。您可以通过桌面应用、iPhone 应用或 openbot.run/app 使用它，就像使用托管服务器一样。您从终端安装和控制它。

若要在容器中运行，请参阅 Docker。

安装¶

在带有 systemd 的 Ubuntu 24.04 或 26.04（x86_64 或 arm64）上：

curl -fsSL https://raw.githubusercontent.com/nightly-labs/openbot/main/scripts/install-server.sh | sudo bash
sudo openbot login

openbot login 会询问您的电子邮件以及 OpenBot 发送到该邮箱的验证码。登录后，服务器会显示在该账户的服务器列表中。其名称为“OpenBot”；您可以使用 sudo openbot login --name <name> 或 sudo openbot name <name> 来指定其他名称。名称长度为 6 到 32 个字符。然后，像在托管服务器上一样，从应用连接提供商（参见提供商）。

使用服务器领取码登录¶

为他人设置服务器的操作员无需验证码即可将其登录。操作员为所有者的电子邮件创建一个一次性领取码，服务器随后兑换该领取码。所有者无需执行任何操作：当他们使用该电子邮件登录 OpenBot 时，服务器就在他们的服务器列表中。

printf '{"email":"%s"}' owner@example.com |
  curl --fail -sS -X POST https://api.openbot.run/v2/admin/server-claims \
    -H @server-claims.header -H 'content-type: application/json' --data-binary @- |
  sed -n 's/.*"claim":"\([A-Za-z0-9_-]*\)".*/\1/p' |
  sudo openbot login --claim --name <name>

server-claims.header 包含一行 Authorization: Bearer <token>，这样令牌就不会出现在进程参数中。出于同样的原因，openbot login --claim 从标准输入读取领取码，或在终端中无回显地询问。

• POST /v2/admin/server-claims 需要账户服务的 SERVER_CLAIMS_ADMIN_TOKEN。当该电子邮件不存在账户时，它创建该账户，并返回 {"claim", "expiresAt"}。
• 领取码只能使用一次，有效期 15 分钟。账户服务只保存其哈希值。
• 服务器将其发送到 POST /v2/server-claims/redeem，并获得所有者的一次会话。此后所有者就是该服务器的唯一所有者。操作员不需要所有者的电子邮件或密码。
• 已使用或已过期的领取码会返回 server_claim_invalid。如果服务器未收到响应，请创建新的领取码。

任何拥有管理员令牌的人都可以为任意电子邮件获取会话，包括现有账户。令牌只能保存在操作员的计算机上。所有者可以在其账户会话中看到每个已领取的服务器会话，并在那里撤销。

安装选项位于 sudo bash -s -- 之后：

再次运行安装脚本可重新安装或升级。数据保留在服务用户的主目录中。重新安装会保留用户和账户服务器，因为登录信息属于它们，并且会拒绝另一个 --user。未使用 --display-size 的重新安装会保留显示大小。安装程序会拒绝低于已安装版本的旧版本，因为旧版 OpenBot 无法打开新版 OpenBot 迁移过的数据库。如果计算机本身是托管服务器，它也会拒绝安装。

命令¶

使用 sudo 或以服务用户身份运行账户命令。其他用户无法打开控制套接字。

内存¶

自托管服务器使用与托管服务器相同的内存保护机制（参见内存）。当可用内存不足时，新的回合会在队列中等待，并在内存可用时重新开始。来自人的消息会优先启动。浏览器不会打开新标签页，并会更快地卸载空闲页面。同一时间运行的回合数量是固定的：内存不超过 5 GiB 时为 2，不超过 10 GiB 时为 8，更高时为 16。

内存上限取机器内存与 openbot.service 的限制（MemoryMax=90%）两者中的较小值。若要为 OpenBot 分配更少内存，可使用 sudo systemctl edit openbot.service 调低限制，例如 MemoryMax=2G，然后重启服务。回合上限和低内存级别随后会使用新的上限。openbot status 显示上限、可用内存、级别（ok、low 或 critical）以及回合上限：

Memory: 1228 MiB free of 3481 MiB (ok)
Turns at the same time: at most 2

该保护机制读取 cgroup v2。在 cgroup v1 系统上，它使用机器内存，并且日志中有一条警告。

代理进程以 nice 10 和 OOM 值 500 运行，包括代理分离出的任务。在 critical 级别下，OpenBot 会先停止残留的代理进程。代理的 Node 程序会在 os.cpus() 中看到单元的 CPU 限制。参见代理进程。

显示大小¶

自托管服务器为代理提供虚拟显示（Xvfb），computer use 读取该显示。默认大小为 1280x800。Docker 容器使用相同的设置和相同的默认值。托管服务器为代理提供其船载桌面，此设置不会更改该桌面。

显示大小不会改变 OpenBot 浏览器（openbot_browser）。其页面有自己的大小，在没有面板显示它们时为 1200x800，并且其点击会作用于页面元素。

若要使用其他大小，请在安装时使用 --display-size 1920x1080 指定，或在 /opt/OpenBot/hosted/openbot.env 中写入以下行，然后运行 sudo openbot restart：

OPENBOT_DISPLAY_SIZE=1920x1080

该值为 WIDTHxHEIGHT 形式的数字，范围从 640x480 到 2576x2576。安装程序会拒绝无效的值。启动时，无效值会在 openbot logs 中写入此警告，服务器将以 1280x800 启动：

OPENBOT_DISPLAY_SIZE is not WIDTHxHEIGHT from 640x480 to 2576x2576. The display is 1280x800.

使用哪种大小¶

除非代理使用的应用需要更多空间，否则请保持 1280x800。在 1280x800 下，computer use 点击更准确，截图消耗更少的 token。只有能完整读取 1920x1080 图像的模型才使用 1920x1080（请参阅 截图与点击）。

一次点击测试比较了这两种大小。一个模型在几乎占满显示的 xmessage 窗口中点击一个 26x17 px 的按钮，分别基于全屏截图和窗口截图各点击一次。这些模型是带图像输入的免费 OpenCode 模型（OpenCode 1.18.30、Docker 镜像 0.42.0、arm64）：

Claude 和 Codex 模型未参与测试。

在 Claude 上，一张图像消耗 ⌈width / 28⌉ × ⌈height / 28⌉ 个视觉 token。1920x1080 的全屏截图所消耗的 token 约为 1280x800 截图的 2 倍：

截图与点击¶

computer use 驱动程序（cua-driver，cua-driver-rs-v0.34.0）在 Linux 上有两种截图：

• 单窗口（get_window_state）。驱动会将图像缩小到 1.15 兆像素或更小，长边为 1568 px 或更短，并将每次点击的 x 和 y 转换回屏幕像素。1260x780 的窗口会以其完整大小到达模型。1900x1060 的窗口会以 1435x801 到达模型。此时小控件更难被点中，而且有些模型会以屏幕像素发送 x 和 y，导致点击落在控件之外。超出显示边缘的窗口不会产生截图。
• 全屏（get_desktop_state）。驱动会以完整大小发送图像，并将点击的 x 和 y 视为屏幕像素。只有当模型以完整大小读取图像时，点击才能正确落位。

模型从 1920x1080 的全屏截图中读取到的是什么：

任何 Claude 或 Codex 模型都不会缩小 1280x800 的截图。

手机应用¶

手机应用没有电子邮件登录。它通过 Mobile Connect 代码登录。服务器没有显示代码的屏幕，因此 openbot mobile-connect 会在终端中显示它：

1. 使用 openbot login 登录服务器。
2. 运行 openbot mobile-connect。在容器中，运行 docker exec -it <container> openbot mobile-connect。
3. 在手机应用中选择 扫描二维码，然后扫描终端中的代码。

该代码让手机登录到服务器的账户。它只对一次登录有效，两分钟后过期。随后手机会显示该账户的所有服务器，并首先打开此服务器。与桌面应用一样，手机通过账户服务器和 Signal 连接。服务器不发布任何端口。

如果手机应用已通过桌面应用连接到同一账户，则该服务器已在服务器列表中。在桌面应用的 设置 > Mobile Connect 中，将手机从账户中移除。

卸载¶

sudo openbot uninstall 会先注销，然后移除服务、单元、AppArmor 配置文件、openbot 命令以及 /opt/OpenBot 中的服务器文件。它会保留服务用户的主目录和 /srv/openbot-hosted 中的密钥环。密钥环保存着该主目录中加密数据的密钥，因此请将两者一起保留或一起删除。使用相同 --user 的安装会再次使用它们。若要同时删除数据：

sudo userdel --remove openbot && sudo rm -rf /srv/openbot-hosted

服务器仍会留在该账户的服务器列表中，处于离线状态。请在列表中移除它。

工作原理¶

install-server.sh 只下载发布版本。它读取最新 GitHub 发布版本中的 latest-linux.yml（在 arm64 上为 latest-linux-arm64.yml），检查 AppImage 的 SHA-512，解包并运行该发布版本中的 resources/hosting/openbot-server-setup。因此，安装步骤始终与它们所安装的构建版本相匹配。在此功能之前的发布版本没有 setup 文件，安装会停止并显示一条消息。

openbot-server-setup 使用托管服务器的安装步骤（openbot-hosted-update）：安装 packages.txt 中的软件包，将发布版本复制到 /opt/OpenBot/app，并安装脚本、AppArmor 配置文件和单元。它将 self 写入 /opt/OpenBot/hosted/mode，并链接 /usr/local/bin/openbot。

当 mode 设置为 self 时，openbot-hosted-server 不会等待 claim（认领）或 boat 桌面。它会像在托管服务器上一样，启动一个带有已解锁密钥环的 D-Bus 会话，并在 Xvfb 下以 OPENBOT_SERVER=1 运行 OpenBot。随后，Main（src/main/server-mode.ts）会打开控制套接字 /run/openbot/control.sock，并在每次登录后发布主机。

该服务器有两个 Xvfb 显示，分别位于两个共享同一授权文件的嵌套 xvfb-run 命令中。外层命令启动代理显示，尺寸为显示尺寸，脚本将其命名为 OPENBOT_AGENT_DISPLAY。内层命令启动 OpenBot 用于显示其窗口的显示，尺寸为 1280x800。Main 将该显示提供给 Computer Use、远程桌面以及代理进程，因此代理的截图和远程桌面不会显示 OpenBot 窗口。参见 Computer Use 和远程桌面。

更新机制与托管服务器上相同（参见 Updates）：定时器会暂存新版本，它会在下次启动时，或当所有者、管理员或受许可成员在 Server Settings > Updates 中安装它时开始运行。sudo openbot update 会暂存、停止服务、应用更新并重新启动服务。当某个步骤失败或收到信号而停止时，该命令会完成被中断的复制、启动服务，并以错误码退出。

控制套接字¶

openbot 命令通过 Unix 套接字上的 HTTP 与 main 通信，使用表单主体和 key=value 文本应答，因此它只需要 curl。路由包括 GET /v1/status、POST /v1/login/start、POST /v1/login/verify、POST /v1/login/claim、POST /v1/name、POST /v1/mobile-connect 和 POST /v1/logout。

威胁模型：

• systemd 以模式 0700 为服务用户创建 /run/openbot，main 将套接字设为 0600。当目录属于其他用户或允许其他用户进入时，main 会拒绝监听。它绝不会删除套接字路径上非套接字的文件。
• 只有服务用户和 root 可以连接。代理以服务用户身份运行，并且已经能够完全访问其文件、密钥环和 OpenBot 数据库，因此该套接字不会给它们带来任何新的权限。
• 该套接字只应答一组固定的请求。它绝不会回传会话令牌、登录码或 claim（认领），且某个值无法在应答中新增一行。请求主体最多为 4 KiB。
• 服务器模式仅在设置了 OPENBOT_SERVER=1 的打包 Linux 构建中启动，绝不会在托管服务器上启动，后者使用其 claim 进行登录。

尚未确认¶

• 完整安装仅在测试中运行于 Ubuntu 24.04。在 Debian 12 和 Debian 13 上，只测试了软件包步骤（apt-get --dry-run）。Debian 12 对某些库的命名不带 t64 后缀，安装过程使用这些名称。
• Ubuntu 26.04：版本 0.48.1 在 Docker 镜像中的 Ubuntu 26.04.1 arm64 上进行了测试，使用 BASE=ubuntu:26.04 以及不含 libminiupnpc17 的软件包列表（0.48.1 的列表会中止该构建）。服务器在启用 Electron 沙箱的情况下启动，openbot status 正常应答，并以退出码 0 停止。带 systemd 的安装和原生 x86_64 运行未经过测试。
• Ubuntu 26.04 上的远程桌面：运行时构建使用 ldd 检查 x86_64 运行时能在其中找到其所有库（参见 Linux 运行时）。在模拟环境下的 x86_64 Docker 镜像中，Sunshine 和 Moonlight Web 成功启动。Ubuntu 26.04 上的流式远程桌面会话未经过测试。
• 在首个包含安装文件的版本发布之前，完整安装未曾在 Linux 计算机上运行。它需要发布构建。
• 显示尺寸：显示尺寸、警告以及使用无效值启动的情况已在 Docker 镜像中测试。带 --display-size 的安装未运行过。点击测试只在 arm64 上运行，使用一个 xmessage 按钮，每种模型、尺寸和截图各运行一次。Claude 和 Codex 未包含在内。超出显示边缘的窗口仅用 xmessage 测试过。窗口截图限制来自 cua-driver 源码（platform-linux/src/tools/impl_.rs 中的 get_window_state 和 get_desktop_state），Claude 的限制来自 Claude 文档。Codex 的限制来自 codex-rs/utils/image，并且未再次检查。目前尚不清楚 Claude Code 或 Codex 在发送给模型之前是否会缩小截图。
• 两个显示在 Ubuntu 24.04 容器中使用 OpenBot 的替身进行了测试：OpenBot 获得 1280x800，代理显示获得显示尺寸，没有授权文件的进程无法打开代理显示。代理显示上的 Computer Use 和远程桌面未在服务器上测试。