SSH (VPS) 远程主机引擎 · 使用说明

让 OpenMausBot 的 bot「住」在你自己的服务器上：agent 进程、文件读写、shell 命令全部原生在 VPS 执行。
界面入口：任意会话的模型/引擎选择器选 SSH (VPS)，或把某个 bot 的默认引擎设为它。

一、原理

OpenMausBot 通过 SSH 在你的服务器上启动 opencode acp（agent 进程），两者之间用 ACP 协议经 SSH 管道通信：

OpenMausBot (本机) ──ssh 管道──> 服务器上的 opencode (agent)
                                  ├─ 文件读写：在服务器
                                  ├─ shell 命令：在服务器
                                  └─ 模型调用：服务器 → 你的模型套餐(z.ai 等)

• 引擎由 App「设置 → 连接」里的 VPS SSH 别名 驱动，改别名即换服务器；
• 会话工作目录 = 服务器上运行用户的主目录（如 /root）；
• 与 App 内置的「云端计算机 / 本地虚拟机」互不影响——那些是容器桌面，本引擎是整机控制。

二、服务器准备（一次性，约 5 分钟）

对一台能 SSH 登录的 Linux 服务器（Ubuntu / Debian 均可）：

# 1. 安装 Node.js 18+（已装可跳过）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

# 2. 安装 opencode
npm install -g opencode-ai

# 3. 登录模型套餐（二选一）
#    方式 A：直接在服务器上登录（推荐，例如 z.ai coding plan）
opencode auth login
#    方式 B：从本机拷贝授权文件到服务器同路径
#    本机 ~/.local/share/opencode/auth.json → 服务器 ~/.local/share/opencode/auth.json

# 4. 验证：能列出模型即成功
opencode models

建议：服务器登录使用密钥认证。机器人是无人值守运行的，密码登录无法自动应答。

三、本机（运行 OpenMausBot 的电脑）配置

1. 建 SSH 别名：编辑 ~/.ssh/config（Windows 为 C:\Users\你\.ssh\config）：

Host myvps HostName 你的服务器IP User root IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes

Windows 自带 OpenSSH 会对 .ssh 下的文件做权限检查，若报 Bad permissions，在 PowerShell 执行：
powershell icacls C:\Users\你\.ssh\config /inheritance:r icacls C:\Users\你\.ssh\config /grant:r "$env:USERNAME:F"
（对私钥文件同样执行一遍。）

1. 打通免密（一次即可，之后永久免密）：

bash # macOS / Linux ssh-copy-id myvps # Windows（无 ssh-copy-id 时） type C:\Users\你\.ssh\id_ed25519.pub | ssh root@你的服务器IP "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"

验证：ssh -o BatchMode=yes myvps "echo ok" 输出 ok 即成功。

1. 在 App 里填别名：设置 → 连接 → VPS SSH 别名 = myvps，保存后重启一次 App。

2. 启用引擎：任意会话的模型/引擎选择器选 SSH (VPS) → 模型选 zai-coding-plan/glm-5.3-flash（或你套餐里的其他模型）；也可以新建一个 bot 把默认引擎设为它（推荐，例如建一个「服务器运维岗」）。

3. 测试：对该 bot 说「看看这台机器的磁盘和内存」，它应返回服务器的真实信息。

四、常见问题

五、给开源打包者的说明

• 本引擎相关补丁都在服务端 resources/server/index.js（decodeAcpConfig / createAcpDriver 的 remoteWorkspace・useVpsAlias 逻辑）与实例配置 instances.vps，随安装包分发即自带；
• 打包前记得把打了补丁的 app 目录重新走一遍 electron-builder 流程（--prepackaged），否则安装包里是未打补丁的原版；
• 界面精简类补丁（菜单项、设置分区、引擎图标）依赖压缩后的变量名，App 大版本升级后需按新 bundle 重打。

文档对应版本：OpenMausBot 0.1.84 修复版 · opencode 1.18.x · 2026-09-25