MengBotDocs
自托管

在 VPS 上部署

从一台空白 Linux 服务器到 MengBot 全天候运行,可从你的笔记本电脑、桌面应用和手机访问。

三种接入方式,一次登录

一条命令获得公网地址、用 Docker 使用你自己的域名,或使用你的 Tailscale 网络。无论选哪种,设备只需用短码配对一次即可保持登录:会话持续 30 天,在剩余时间不足一半时使用会续期至完整 30 天,自配对起最长 180 天。经常使用的设备每年重新配对两次;闲置一个月的设备需要重新配对。无需密码。

从一台空白 Linux 服务器到 MengBot 在其上全天候运行,可从你的笔记本电脑、桌面应用和手机访问,即使所有笔记本电脑都合上,你的机器人仍在工作。本指南假设你只会打开终端并粘贴命令。大约二十分钟,大部分时间在等待。

本指南涵盖三种让服务器可访问的方式。选一种;其余步骤相同。

你需要谁可以访问最适合
A. 公网地址,无域名(serve --tunnel)一个 MengBot 账户(邮件验证码)任何持有配对码的人,通过 HTTPS最快的路径;使用蜂窝网络的手机
B. 你自己的域名(Docker + Caddy)一个域名,端口 80/443任何持有配对码的人,通过 HTTPS你拥有的永久地址
C. 你的 Tailscale 网络(serve --tailscale)服务器和你的设备上都安装 Tailscale仅你的 tailnet最私密;完全不公开

无论选哪种,登录方式相同:你用短码将每台设备配对一次,之后保持登录。会话持续 30 天;在剩余时间不足一半时使用会续期至完整 30 天,自配对起最长 180 天(OMB_SESSION_TTL_DAYS 和 OMB_SESSION_MAX_DAYS 可修改这两个数值)。没有密码。

Hetzner 启动检查(2026-09-07)

路径 A 在一台空白 Hetzner CX43(x86-64,Ubuntu 24.04)上进行了验证,使用 Node 24.20.0 和 Codex 0.153.4。在已发布的 0.1.60 基线之后,应用了本次变更中的 本地候选修复;这些结果并不证明未经修改的已发布 0.1.60 包。

配对后的 Web UI 完成了一次真实的 GPT-6-Astra 对话、两次自动 调度的例程运行,以及一次浏览器标题/截图测试。浏览器 需要下面的 Ubuntu 沙箱设置。完整重启后,服务和 托管隧道自动恢复;已有的配对设备、机器人、对话 和暂停的调度仍然可用。一次新的真实对话轮次也成功了。

停止应用数据后的备份恢复后,文件哈希和 SQLite 完整性均匹配。恢复的副本未启动;提供商重新认证 和浏览器登录迁移未测试。Docker、Tailscale、ARM64、其他 提供商和容量限制不在本次运行范围内。

服务器上运行什么,不运行什么

完全在服务器上运行:每个引擎 CLI(Claude Code、Codex、Grok、自定义 ACP 引擎)、对话、房间、机器人间协调、例程、已连接应用和自定义 MCP 服务器、webhook、Company Brain、云端或容器计算机上的计算机使用、文本转语音,以及 Web UI(服务器自行提供)。

需要改用桌面应用:听写和控制服务器自身的桌面。安装浏览器引擎后(见下文),机器人也可以在服务器上浏览。

开始之前

  1. 一台服务器。 任何 Linux VPS:Ubuntu 22.04 或 24.04,2 个 CPU 和 4 GB 内存足够。你需要 sudo 或 root 权限。Hetzner、DigitalOcean、Lightsail、柜子里的 Mac mini:都可以。

  2. Node 24 或更新版本,用于路径 A 和 C(node --version)。在 Ubuntu 上:

    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs

    路径 B 改用 Docker,主机上无需 Node。

  3. 你的引擎账户。 机器人运行在你笔记本电脑上使用的相同引擎 CLI 上,使用你的订阅。你在服务器上以相同方式登录一次。

连接服务器以执行以下所有操作:

ssh root@YOUR_SERVER_IP

对于路径 A 和 C,设置和运行服务使用同一个非特权 Linux 账户。 以下示例使用 meng,主目录为 /home/meng。在管理员 shell 中, 如果该账户尚不存在则创建它,然后切换过去:

sudo useradd --create-home --shell /bin/bash meng
sudo -iu meng

登录 shell 也会切换到 /home/meng;在那里运行设置,而不是从 /root。 在此账户中运行下面的 npx 命令和引擎登录。保留一个单独的 管理员 shell 用于系统包和 systemd。如果你已经以 root 登录,请重新以 meng 登录;这些账户有不同的主目录和凭据。

路径 A:一条命令获得公网地址

无需域名、无需代理、无需开放端口。服务器通过 Cloudflare 隧道获得类似 https://c-7f3a9c.mengbot.com.cn 的地址;只有通过隧道的流量才能到达它,而且该流量仍需配对。

npx mengbot login          # 一次:邮件验证码登录此机器并预留其地址
npx mengbot serve --tunnel # 在那里运行服务器并打印带二维码的配对链接

login 会询问你的邮箱,发送 8 位验证码,并打印为此机器预留的地址。serve --tunnel 首次运行时会下载 cloudflared(固定版本并验证摘要,存入 ~/.mengbot),启动服务器,连接隧道,几秒后打印 tunnel: live at https://…。让它保持运行;服务配置见“保持运行”。

账户凭据位于 ~/.mengbot/tunnel-account.json,仅你的用户可读。npx mengbot logout 释放该地址。

跳到“安装并登录引擎”。

路径 B:使用 Docker 和你的域名

一个容器运行服务器,加上 Caddy 在 https://meng.example.com 提供 HTTPS。

  1. 将域名指向服务器。 在你的 DNS 提供商处添加一条 A 记录(名称 meng,值为服务器的公网 IP)。几分钟后 ping meng.example.com 应返回该 IP。端口 80 和 443 必须开放;大多数提供商默认开放。

  2. 安装 Docker:

    curl -fsSL https://get.docker.com | sh
    docker compose version   # 打印版本;如果显示 "command not found",注销后重新登录
  3. 获取部署文件并设置域名:

    git clone https://github.com/EternalNight996/mengbot && cd MengBot/deploy
    cp .env.example .env
    nano .env                # DOMAIN=meng.example.com ; ENGINES=@anthropic-ai/claude-code @openai/codex

    ENGINES 列出烘焙进镜像的引擎 CLI,以空格分隔。之后添加引擎时修改它并重新构建。

  4. 启动:

    docker compose pull omb && docker compose up -d
    docker compose ps        # omb "healthy",caddy "running"

    Caddy 会自行申请证书;给它一分钟。然后 https://meng.example.com 会显示一个要求配对码的页面。这是正确的:配对之前一切都不工作。

在此路径中,下面每个 npx mengbot … 命令改为在容器内运行:

docker compose exec omb node dist-server/mengbot.js pair --label "My MacBook"

在 ARM64 上:Raspberry Pi 4/5 和 ARM 服务器

镜像同时发布为 linux/amd64 和 linux/arm64,Docker 会拉取与机器匹配的版本,因此上述步骤在 ARM64 服务器或 Raspberry Pi 4 或 5 上相同。使用 64 位系统(Raspberry Pi OS 64 位或 Ubuntu Server for ARM;uname -m 输出 aarch64)以及至少 4 GB 内存。当你修改 ENGINES 时,docker compose build 会在 机器本身上构建镜像。

在 ARM64 上,机器人的浏览器是 Debian 的 Chromium,因为 Chrome for Testing 没有 Linux ARM64 构建。运行后,从任何 浏览器打开 https://meng.example.com 并按下面所述配对。

路径 C:仅你的 Tailscale 网络

在管理员 shell 中,在服务器上安装 Tailscale 并登录(curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up)。在管理控制台(DNS → HTTPS Certificates)为你的 tailnet 启用一次 HTTPS 证书,然后从 meng shell 运行:

npx mengbot serve --tailscale

Tailscale 使用自己的证书终止 HTTPS,配对链接使用服务器的 MagicDNS 名称(https://meng.tail1234.ts.net)。只有你 tailnet 上的设备可以访问它,这对于一个能运行工具的服务器来说是非常好的特性。

给机器人一个浏览器(可选)

机器人可以在服务器上浏览。Docker(路径 B)在镜像中自带引擎和 Chrome。 对于路径 A 和 C,先从管理员 shell 安装一次 Linux 系统库:

sudo -H npx --yes mengbot browser install --with-deps

然后从 meng shell 在服务账户的主目录中安装浏览器:

npx --yes mengbot browser install

管理员的浏览器下载位于不同的主目录;它不会安装 服务账户的浏览器。两条命令都必须成功完成。

在 Ubuntu 24.04 上,AppArmor 可能还需要管理员沙箱设置。 一键安装器下载浏览器;它不会授予这些操作系统权限。

然后在设置 → 实验性中开启浏览器,并按机器人开启。每个机器人 获得自己隔离的会话,其登录在重启后保持。

安装并登录引擎

npm MengBot 包不安装模型引擎 CLI。对于路径 A 和 C, 在服务账户中安装你使用的引擎,然后登录。例如, 从 meng shell,对于 Claude:

npm install --global --prefix "$HOME/.local" @anthropic-ai/claude-code
export PATH="$HOME/.local/bin:$PATH"
claude

对于 Codex,使用 @openai/codex 作为 npm 包并运行 codex login --device-auth 从无头服务器登录。在浏览器中完成 CLI 的账户流程。仅对你使用的 引擎重复。对于路径 B,在容器内运行已安装的 CLI,例如 docker compose exec omb claude。

引擎登录属于服务用户的主目录(例如 ~/.codex 和 ~/.claude),与 MengBot 的 ~/.mengbot 分开。重启或升级时 保留该主目录。下面的 systemd 示例在 PATH 中包含 ~/.local/bin。

配对第一台设备

serve 启动时已经打印了配对链接和二维码。之后为另一台设备:

npx mengbot pair --label "Kitchen iPad"
pairing code:  RR8Y-BLR6-H939
expires:       10:59:45 AM (single use)
open or scan:  https://c-7f3a9c.mengbot.com.cn/pair#code=RR8Y-BLR6-H939
  • 浏览器: 打开链接。验证码已填入;按 Connect。该浏览器配对 30 天,使用时按上述方式续期。
  • 桌面应用: 复制链接,然后在应用的 Server 菜单中选择 Add Server from Copied Pairing Link…。该菜单在你自己的机器和你添加的每台服务器之间切换。
  • 手机: 从 iOS 应用的配对屏幕扫描二维码,或将整个链接粘贴到其地址栏。手机可以聊天、批准和阅读;创建机器人、更改模型和连接应用仍在服务器的 UI 中由你操作。

值得了解:验证码只能使用一次,五分钟后过期;链接只在该地址有效(手动输入验证码:打开 …/pair 并输入);一分钟内从同一地址输入十次错误验证码会暂停该地址的配对一分钟;--client 为可以聊天和批准但不能更改设置或配对其他设备的设备生成验证码。

管理设备

每台配对设备都是一个会话:

npx mengbot sessions              # id、设备、范围、最后活动、过期时间
npx mengbot sessions revoke ID    # 立即将该设备登出并关闭其流
npx mengbot status                # 服务器对自身的报告

保持运行

npx mengbot serve 是一个普通的前台进程。对于 systemd(路径 A 和 C), 先从 meng shell 安装选定的发布版本。将 X.Y.Z 替换为 你想运行的已发布版本:

npm install --global --prefix "$HOME/.local" mengbot@X.Y.Z

在启用服务前用 Ctrl-C 停止前台服务器。从 管理员 shell,将其保存为 /etc/systemd/system/mengbot.service:

# /etc/systemd/system/mengbot.service
[Unit]
Description=MengBot server
After=network-online.target

[Service]
User=meng
WorkingDirectory=/home/meng
Environment=HOME=/home/meng
Environment=PATH=/home/meng/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/meng/.local/bin/mengbot serve --tunnel --no-pair
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload && sudo systemctl enable --now mengbot
journalctl -u mengbot -f            # 服务器日志,包括 "tunnel: live at …"

路径 C 使用 --tailscale 代替 --tunnel。--no-pair 跳过每次重启时打印验证码;需要时用 npx mengbot pair 生成一个。Docker(路径 B)自行重启(restart: unless-stopped)。

如果你的账户、主目录和 PATH 不同,请相应调整;该 PATH 上必须可用 Node 24。服务直接运行已安装的 CLI,因此重启使用 同一发布版本,不会出现 npm 安装提示或隐式升级。

更新

  • 使用上述服务的路径 A 和 C: 选择新的已发布版本, 然后从管理员 shell 运行这些命令,替换 X.Y.Z:

    sudo systemctl stop mengbot
    sudo -iu meng npm install --global --prefix /home/meng/.local mengbot@X.Y.Z
    sudo systemctl start mengbot

    启动前检查安装是否成功。仅重启服务 不会更新已安装的包。对于前台 npx 用法,指定 所需发布版本为 npx --yes mengbot@X.Y.Z serve --tunnel。

  • 路径 B: cd MengBot/deploy && docker compose pull omb && docker compose up -d。

例程和排队的工作在重启后保留;当时正在运行的轮次不会,因此请在运行间隙更新。

备份

在复制 SQLite 数据库前停止服务器:前台进程用 Ctrl-C, 或从管理员 shell 对上述服务运行 sudo systemctl stop mengbot。停止任何仍在写入 你打算备份的文件的引擎进程和托管桌面。

对于路径 A 和 C,这会备份应用状态(机器人、对话、例程、隧道 凭据和配对会话)。从服务账户的 shell 运行:

umask 077
backup_dir=$(mktemp -d "$PWD/mengbot-backup.XXXXXX")
tar czf "$backup_dir/mengbot-data.tgz" -C "$HOME" .mengbot

完整备份还需要你的引擎凭据/配置路径,例如 ~/.codex、~/.claude 和 ~/.claude.json,以及使用时的浏览器会话状态 ~/.agent-browser。包含你已安装 CLI 存在的路径、 任何配置的主目录/数据目录覆盖,以及应用目录之外的工作区。 这些不包含在上面的命令中。

对于路径 B,整个 /data 卷包含容器的 CLI 主目录。从 MengBot/deploy,在归档前停止应用;deploy_data 是默认 卷名,如果你更改了 Compose 项目,请使用实际的卷名:

docker compose stop omb
backup_dir=$(mktemp -d "$PWD/mengbot-backup.XXXXXX")
docker run --rm -v deploy_data:/data:ro -v "$backup_dir":/b alpine sh -c 'umask 077; tar czf /b/mengbot-data.tgz -C /data .'

每条命令在当前目录创建一个新的私有文件夹,因此 不会用权限更宽松的旧归档覆盖。将 归档私密地保存在另一台机器上的该文件夹内。在服务器停止时恢复, 使用相同的路径和原始所有权。备份或恢复后,用 sudo systemctl start mengbot 或 docker compose start omb 启动服务。

设置所依赖的规则

在服务器前面放置任何其他东西之前请阅读此节。

  • 服务器只监听回环地址(127.0.0.1:8799)。绝不要自行发布该端口。隧道、Caddy 和 Tailscale 都从同一台机器访问它。
  • 通过代理或隧道到达的请求被视为远程请求,无论携带什么标头都需要会话。你自己的代理(nginx、Traefik、Cloudflare Tunnel)必须转发真实的 Host 并添加 X-Forwarded-For 和 X-Forwarded-Proto,不得缓冲事件流,并且不得将 Host 重写为 127.0.0.1。
  • 配对就是登录。想在它前面再加一道墙?路径 B 的 Caddyfile 有一个注释掉的 basic_auth 块用于共享密码。
  • 会话 cookie 标记为 Secure;不要在公网互联网上通过纯 HTTP 提供此服务。
  • 陌生人唯一能读取的是 /.well-known/mengbot/environment(服务器的 id、标签、版本、能力)和 /api/health(仅应用名称)。其他所有内容都回答“请配对此设备”。

故障排除

serve --tunnel 显示 "no account on this machine yet"。 先在此机器上运行 npx mengbot login;凭据是按机器存储的。

隧道一直显示 "retrying"。 服务器正在运行且本地可用;公网跳转尚未验证。等一分钟(Cloudflare 在新地址上需要一点时间),然后检查 journalctl/终端了解原因。如果始终无法启动,npx mengbot logout && npx mengbot login 会签发新地址。

路径 B:页面无法加载或显示证书错误。 Caddy 无法获取证书。检查域名是否解析到服务器以及端口 80 和 443 是否开放;docker compose logs caddy 显示原因。

"forbidden: pair this device to use the server remotely" / "this request came through a proxy"。 配对前以及对于没有会话调用 API 的工具来说是预期的。请配对设备。脚本发送 Authorization: Bearer <token>,使用配对响应中的令牌而不是 cookie。

配对码被拒绝。 它已过期(五分钟)或已被使用。生成一个新的。"Too many failed pairing attempts" 表示等待一分钟。

机器人说引擎未登录。 在服务器上重新登录该引擎。

服务器认为它是什么? https://<address>/.well-known/mengbot/environment 是公开的,显示其 id、标签、版本和能力;npx mengbot status 在服务器上打印相同内容。

其他问题。 journalctl -u mengbot --since -10m(或 docker compose logs omb --tail 100)显示服务器的启动行。将它们连同你的问题粘贴到社区频道。

Ubuntu 24.04 浏览器沙箱

如果 Chrome 报告 No usable sandbox! 且 sudo journalctl -k --since -10m 显示针对 userns 的 AppArmor DENIED,浏览器下载已安装但 Ubuntu 阻止了其沙箱。Chromium 记录了此限制。 不要添加 --no-sandbox 或全局禁用 kernel.apparmor_restrict_unprivileged_userns。

对于路径 A 和 C,管理员可以仅允许受信任的、root 拥有的 Chrome 副本。找到服务用户下载的可执行文件:

find /home/meng/.agent-browser/browsers -type f -name chrome -executable

在下面的每个路径中使用其实际的 chrome-VERSION 目录;VERSION 是 占位符,不是固定的 Chrome 发布版本。将整个目录(包括其 库)复制到服务用户无法修改的新位置:

sudo install -d -o root -g root -m 0755 /opt/mengbot-browser
sudo cp -R /home/meng/.agent-browser/browsers/chrome-VERSION /opt/mengbot-browser/
sudo chown -R root:root /opt/mengbot-browser/chrome-VERSION
sudo chmod -R go-w /opt/mengbot-browser/chrome-VERSION

将其保存为 root 拥有的 /etc/apparmor.d/mengbot-chrome,将 VERSION 替换为相同的值。保持精确的可执行文件路径:可写的 服务主目录下的通配符也会允许替换可执行文件。

abi <abi/4.0>,
include <tunables/global>

profile mengbot-chrome /opt/mengbot-browser/chrome-VERSION/chrome flags=(unconfined) {
  userns,
}

加载配置文件:

sudo apparmor_parser -r /etc/apparmor.d/mengbot-chrome

在上面的 systemd 单元的 [Service] 下添加以下行,再次使用 精确的已安装版本,然后运行 sudo systemctl daemon-reload 和 sudo systemctl restart mengbot:

Environment=AGENT_BROWSER_EXECUTABLE_PATH=/opt/mengbot-browser/chrome-VERSION/chrome

对于前台服务器,在启动 serve 之前,在 meng shell 中将 AGENT_BROWSER_EXECUTABLE_PATH 导出为同一 路径。Chrome 更新后,复制 新版本并更新 AppArmor 配置文件和服务环境;root 拥有的副本 不会由浏览器安装器更新。保持 kernel.apparmor_restrict_unprivileged_userns=1。

On this page