自购 Ubuntu 主机部署：手机在同一局域网使用 MochiBot
适用于家中或办公室的电脑、小主机。主机使用有线网络或 Wi-Fi，手机连接同一个局域网。首次按本教程只验证同网使用；手机离开这个网络后，不会自动连接回家中主机。 需要随时在外使用，请优先选择云服务器路线 ↗。
两条路线是同一个包：自动安装固定版本 OpenClaw、MochiBot 和 Skills 助手，不先下载大模型；模型 API 在手机配对后填写。无需显卡、无需 USB 调试、无需在 App 注册账户。
全部命令在这台主机的 Ubuntu 终端中执行，不是手机聊天框或 Windows PowerShell。桌面版 Ubuntu 可按 Ctrl+Alt+T 打开终端；服务器版登录后直接使用终端。一次复制一个代码块，按回车，等返回提示符再继续。sudo 如要求密码，输入这台 Ubuntu 登录用户的密码，输入时没有字符显示是正常的。
尚未安装 Ubuntu？先按 Ubuntu 官方桌面安装教程 ↗ 或 Ubuntu Server 安装教程 ↗准备系统，再回到第 1 步。
1. 确认主机系统与空间
需要纯净 Ubuntu 24.04 LTS、x86_64、至少 4GB 内存，多人建议 8GB；建议 40GB 以上系统盘、当前可用空间至少 8GB。尚未安装 Ubuntu 时先使用 Ubuntu 官方安装说明完成系统安装并创建登录用户；本包不会替你格式化硬盘或安装操作系统。
主机需能访问 Ubuntu 软件源、nodejs.org、npm 和所选模型 API。已经有 OpenClaw/MochiBot 的机器不要按纯净流程重装；包发现已有部署会停止。
cat /etc/os-release
uname -m
df -h /
应看到 ID=ubuntu、VERSION_ID="24.04"、x86_64，最后一条的 Avail 列是磁盘剩余空间。ARM/aarch64、Windows 和其他 Ubuntu 版本不按本教程继续。
2. 找到局域网 IP，并确认手机在同一网络
在主机执行：
ip -4 -brief address show scope global
找正在使用的网卡：常见有线网卡以 en 开头，Wi-Fi 以 wl 开头，IPv4 通常形如 192.168.1.100/24。记录斜杠前面的地址，例如 192.168.1.100；不要填 127.0.0.1、docker/veth 网卡地址或云服务器公网 IP。
手机连接同一路由器的普通 Wi-Fi，不用移动数据或访客 Wi-Fi。主机有线、手机 Wi-Fi 可以使用同一局域网，但路由器不能开启客户端隔离。建议在路由器“DHCP 地址保留/静态租约”中将该网卡固定到当前 IP，保存后确认地址没变；重启或换网后地址改变会使原连接失效。
本路线手机入口是 TCP 8443，程序只监听填写的局域网地址。不需要云安全组，也不要为这一步配置公网端口转发。安装程序检测到 UFW 已开启时会添加 8443 规则；不会开启或关闭 UFW。其他主机防火墙需要自行允许局域网手机访问此端口。
3. 准备下载工具
在主机终端逐条执行：
sudo apt-get -o Acquire::Retries=3 -o DPkg::Lock::Timeout=180 -o APT::Update::Error-Mode=any update
这条刷新软件清单。返回命令提示符且没有 E: 错误后，再执行：
sudo apt-get -o Acquire::Retries=3 -o DPkg::Lock::Timeout=180 install -y ca-certificates curl python3
这条安装 HTTPS 下载工具和 Python。若显示等待软件包锁，表示系统自动更新正在运行，先等待；不要删除锁文件。命令失败时先看文末故障处理，不继续执行安装包。
4. 下载部署包并校验
先建一个存放安装包的文件夹，再进入它：
mkdir -p ~/mochibot-setup
cd ~/mochibot-setup
pwd
最后一条显示的路径应以 /mochibot-setup 结尾。下载部署程序：
curl --fail --location --retry 3 --connect-timeout 20 --proto '=https' --tlsv1.2 'https://mochilab.bz/MochiBot/Installer.ashx?version=0.2.7' -o MochiBot-Ubuntu24-x64-online-0.2.7.run
下载对应校验文件：
curl --fail --location --retry 3 --connect-timeout 20 --proto '=https' --tlsv1.2 'https://mochilab.bz/MochiBot/Installer.ashx?version=0.2.7&checksum=1' -o MochiBot-Ubuntu24-x64-online-0.2.7.run.sha256
最后核对是否下载完整、是否为对应版本：
sha256sum --check MochiBot-Ubuntu24-x64-online-0.2.7.run.sha256
应看到 `MochiBot-Ubuntu24-x64-online-0.2.7.run: OK`（中文系统可能显示“成功”）。只有看到这个结果才继续。下载失败或校验失败，不执行 .run 文件，重新执行对应下载和校验命令。
5. 填写局域网 IP，检查并安装
将下面的 你的局域网IPv4 整段换成第 2 步记录的主机地址，保留单引号，不带 /24 等后缀：
SERVER_IP='你的局域网IPv4'
核对变量，输出应为真实 IP，不能是占位文字：
printf '%s\n' "$SERVER_IP"
先只检查本机条件：
sudo bash MochiBot-Ubuntu24-x64-online-0.2.7.run --check --mode lan --address "$SERVER_IP"
应看到“检查通过：Ubuntu 24.04 / x86_64 / 局域网主机”。这不代表手机已经能连，继续安装：
sudo bash MochiBot-Ubuntu24-x64-online-0.2.7.run --mode lan --address "$SERVER_IP"
等待 [1/6] 到 [6/6] 完成。程序自动安装依赖、Node.js 和 OpenClaw，配置独立工作区、HTTPS 和服务；不在终端填写模型 Key。不要同时运行第二份安装，也不要在没结束时重复粘贴命令。成功后显示“服务已启动。模型尚未配置”和配对二维码。
6. 手机安装 App 并扫码
手机打开 MochiBot 下载页 ↗，下载当前版本 APK 并安装（此部署模式需要 1.0.4 或以上）。如提示安装来源权限，仅允许本次所用浏览器或文件管理器。无需 USB 调试，也无需注册 MochiBot 账户。打开 设置 → 扫码连接，允许相机权限，扫描电脑终端二维码，核对服务器和助手后确认绑定。
程序已配置 HTTPS；App 在扫码时绑定服务器公钥指纹。无需自己申请域名或另外购买证书，也不用关闭 App 的证书校验。
二维码 5 分钟有效。如果手机安装时间较长导致过期，在服务器终端执行：
sudo mochibotctl pair
扫描新显示的二维码即可，不要重装服务器。每位新成员要使用自己的独立工作区配对码，不能都扫描第一位使用者的码。
7. 在 App 填写云端模型
打开 设置 → 模型管理 → 添加云端模型：
- 选择 DeepSeek、千问、OpenAI 或兼容 API。
- 填写便于辨认的配置名称、该服务商的 HTTPS API 地址和自己的 Key；千问 Key 与地址必须属于同一地域。API 地址是接口地址，不是网页登录地址。
- 点“读取可用模型”后选择聊天模型；服务商不提供列表时，按其控制台填写准确模型 ID。不要选择图片、语音或嵌入模型。
- 上下文和最大输出有预填值，但不能超出所选模型支持的范围；不支持时按服务商说明调小。
- 点击“测试并保存使用”，看到成功后再返回聊天。测试会产生一次少量 API 调用费用。
没有模型 Key 时，先按 DeepSeek 注册、充值及取 Key 教程 ↗准备。API 费用由对应服务商收取。密钥只填 App 的专用输入框，不发到聊天里。
8. 收到第一条真实回复
在聊天中发送：“你好，请用一句话介绍自己。”
收到正常回复，首次部署就完成了。 不必再做下面的可选设置，才能开始聊天或处理文件。
9. 保持主机可用
主机与路由器需要持续开机联网。桌面 Ubuntu 在“设置 → 电源”关闭自动挂起；笔记本合盖可能休眠，测试期间保持开盖并接电。关闭显示器可以，关机或休眠会停止聊天和服务器提醒任务。程序安装为系统服务，正常重启后自动启动，不需要保持终端窗口一直打开。
手机仍需允许通知与后台运行，才适合接收语音提醒；同网可用不等于手机出门后仍能连接。外出访问需另行部署安全的远程网络入口，不在本教程内开放内网管理端口。
可选：用到时再设置
- Skills 账户：设置 → MochiLab Skills 账户 → 连接 / 管理账户，登录网站取得
mls_ 访问密钥，填回专用输入框并验证。Skills 助手已经安装；会员连接成功后才能下载该账户有权限的内容。各工作区分别连接，授权使用者可连接同一个会员账户。 - 其他家人、同事或朋友：新增独立工作区与配对教程 ↗。每个人的聊天、文件和模型配置独立，App 界面相同。
- 语音提醒：方案、确认、查看及取消教程 ↗。先在提醒页开启接收，允许通知与后台运行；手机和服务器保持联网。
遇到错误再看：不从头重装
下载或安装中断
先确认正在原来的文件夹；以下命令可以重新进入，之前定义的 IP 变量在重新登录后需要重新填写：
cd ~/mochibot-setup
SERVER_IP='你的局域网IPv4'
如果安装已经开始但尚未完成，处理网络或错误提示后，用同一个版本续装：
sudo bash MochiBot-Ubuntu24-x64-online-0.2.7.run --resume --mode lan --address "$SERVER_IP"
--resume 会保留已完成阶段与已校验依赖缓存。不要删除工作区、不要换另一个版本直接续装，不要关闭防火墙或删除系统软件包锁文件。若提示仍有安装进程，先等那次安装退出。已经显示安装完成的主机不走续装流程。
若软件源连接失败，检查网络后重试第 3 步。如果明确提示 dpkg was interrupted，先等其他系统更新结束，再执行 sudo dpkg --configure -a；成功后重新执行第 3 步，再续装。不要在正在运行的 apt/dpkg 上删除锁或强行终止进程。
若停在 [3/6] OpenClaw 且 npm 官方源持续连接失败，可在同版本续装命令末尾增加 --registry https://registry.npmmirror.com。它只切换 npm 依赖源，固定文件完整性仍校验；Node.js 官方下载或模型 API 不通，需要分别解决。
安装显示完成，但手机扫码超时
先核对主机 IP 是否改变、主机是否睡眠、手机是否仍连接同一普通 Wi-Fi、路由器是否开启客户端隔离，以及主机防火墙是否允许 TCP 8443；二维码过期则用 sudo mochibotctl pair 换码。不要因为扫码超时就重新安装服务。
在服务器检查服务：
sudo mochibotctl doctor
应看到 connector、tlsEntry、apiHealthy 为 true，installerState 为 complete。尚未填写模型时 `modelConfigured: false` 正常；在 App 配置模型成功后才应变为 true。
需要查看最近服务错误时执行：
sudo journalctl -u mochibot.service -u mochibot-entry.service -n 60 --no-pager
分享记录前遮盖私人地址与任何凭据。模型测试失败应检查地址、地域、Key、余额和模型 ID；不需要重装 Ubuntu。
可选：已有标准部署更新服务程序
仅适用于已经成功安装的标准部署；先等待各工作区任务完成。重新执行第 4 步的下载和校验命令，看到本版本文件名后跟 OK，再执行：
sudo bash MochiBot-Ubuntu24-x64-online-0.2.7.run --update
应看到“服务器更新完成”和健康服务数。该命令只更新已知服务代码，保留模型密钥、Skills 登录、连接和各工作区；不等于重新执行初始化器，也不替换已安装的 Node.js/OpenClaw。遇到未知本地修改或任务未结束会停止，请按原提示处理；不要改用纯净安装命令。安装中断时仍应使用原版本 --resume，不能用 --update 代替续装。
本教程的验证范围
已有服务器更新、多人独立聊天及手机连接已经实测。当前没有空白测试机，本版本在纯净系统上从第一步到最后一步的完整验收尚待补做；局域网路线也尚未在独立自购主机上全程实测。本文将每步结果和排错写明，但不承诺任意网络与硬件都能一次成功。