moltis

你会遇到什么

这个工具解决什么问题：你要一个常驻的个人 Agent 服务器——安全、持久，对外提供服务（gateway）。Moltis 是 Rust 单二进制：gateway（默认子命令，端口 + 常驻）+ acp/agent/channels/sessions/config/models/providers/onboard/doctor/auth/skills/hooks/sandbox 全命令面。 什么时候用：

• 你要跑一个常驻网关给 Agent 服务（Telegram/WhatsApp 等通道）；
• 你要安全持久化的个人 Agent 服务器（密钥检查、沙箱）；
• 你要用 onboard 向导配 provider/通道/沙箱。

什么时候别用：临时会话、不需要常驻服务时——它是服务器形态（gateway 起进程绑端口）。 注意事项：重档服务器条目——gateway 会常驻并绑定端口；国内直连 GitHub release 资产实测 3KB/s 超时，必须 gh-proxy 前缀。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：Rust 单二进制（release tarball 解压到 /usr/local/bin）。首次运行自动生成 ~/.config/moltis/；doctor 配置/安全检查；onboard 交互式配置 provider/通道/沙箱；gateway 启动常驻网关（Ctrl+C 停止，生产用 systemd 托管）。 关键概念：

• gateway：默认子命令 = 常驻网关服务器（端口绑定，对外提供 agent 服务）；
• onboard：首次配置向导（provider/通道/沙箱，人工介入）；
• doctor：配置/安全检查（TOML 有效、无 API key 泄露）。

装完它动哪里：~/.config/moltis/（配置，首次运行自动生成）+ 数据目录 ~/.local/share/moltis（记忆/会话/通道数据）。

一步步来

第 1 步：装二进制（为什么 gh-proxy：国内直连实测 3KB/s 超时）

讲解：国内直连 GitHub release 资产实测 3KB/s 超时（2026-08-28）——必须走 gh-proxy 前缀（实测 68M/16s）。tarball 解压出 moltis 到 /usr/local/bin。其他平台选对应资产（AppImage/dmg/exe/deb/rpm）。

curl -sL -o /tmp/moltis.tar.gz 'https://gh-proxy.com/https://github.com/moltis-org/moltis/releases/download/20260830.01/moltis-20260830.01-x86_64-unknown-linux-gnu.tar.gz'
tar xzf /tmp/moltis.tar.gz -C /usr/local/bin moltis
moltis --version

预期输出: moltis 20260830.01

装好确认：

• --version 输出 20260830.01；
• /usr/local/bin 可写（前置检查 precheck: OK）。

卡住怎么办：

• 下载慢/超时 → 确认网络能到 gh-proxy；备选 npm/cargo 镜像构建（官方路径，未实测）；
• tar 解压报错 → 重新下载，确认文件完整。

第 2 步：doctor 检查 + onboard 配置

讲解：doctor 全项配置/安全检查（TOML 有效、无 API key 泄露；数据目录权限 warn 可手动 chmod 700）；onboard 交互式向导配置 provider/通道/沙箱（人工介入）。

moltis doctor

预期输出: 配置/安全检查项（TOML 有效、无 API key 泄露；数据目录权限 warn 可手动 chmod 700）

moltis onboard

预期输出: 交互式配置（provider/通道/沙箱；人工介入）

装好确认：

• doctor 全项通过（或只有可手动修的 warn）；
• onboard 完成后配置就位。

卡住怎么办：

• doctor 有 FAIL 项 → 按提示修正（权限/配置）；
• onboard 中途退出 → 可重跑，配置是增量的。

第 3 步：启动 gateway（常驻）

讲解：gateway 是默认子命令，启动常驻网关（端口绑定，对外提供 agent 服务）。Ctrl+C 停止；生产建议 systemd 托管。

moltis gateway

预期输出: 网关启动日志（Ctrl+C 停止；生产用 systemd 托管）

装好确认：

• 启动日志无错误；
• 服务端口可访问。

卡住怎么办：

• 端口被占 → 看配置里的端口设置（~/.config/moltis/）；
• 启动失败 → 先 doctor 检查配置。

怎么确认修好了

第 1 步：确认版本与配置体检

讲解：moltis --version 确认安装；moltis doctor 把配置与安全项跑一遍——全项通过（或只有可手动修的 warn）说明环境就绪。

moltis --version
moltis doctor

预期输出: 20260830.01；配置/安全检查项（TOML 有效、无 API key 泄露；数据目录权限 warn 可手动 chmod 700）

卡住怎么办：

• doctor 有 FAIL 项 → 按提示修正（权限/配置）；
• 版本对不上 → 重新下载并确认文件完整。

第 2 步：确认 gateway 能起（可选，常驻服务）

讲解：moltis gateway 启动日志无错误、服务端口可访问，说明对外服务链路通；不需要常驻时 Ctrl+C 停止。

moltis gateway

预期输出: 网关启动日志（Ctrl+C 停止；生产用 systemd 托管）

卡住怎么办：

• 端口被占 → 看配置里的端口设置（~/.config/moltis/）；
• 启动失败 → 先 doctor 检查配置。

其它环境的表现（常见变体）

• 非 Linux x86_64：官方提供 AppImage/dmg/exe/deb/rpm 等资产（本机未实测，命令面一致）。
• 后台进程：gateway 常驻并绑定端口；生产建议 systemd 托管，开发用 Ctrl+C 停止即可。
• 写面：~/.config/moltis/（配置）+ ~/.local/share/moltis（数据），均为专属目录，无共享注册面，共装判定全部 possible-compatible。

日常使用

启动与入口

• 网关：moltis gateway（常驻）；生产用 systemd 托管；
• 命令面：moltis --help（gateway/acp/agent/channels/sessions/config/models/providers/onboard/doctor/auth/skills/hooks/sandbox）。

常用操作

操作一：查看命令清单

moltis --help

预期输出: gateway/acp/agent/channels/sessions/config/models/providers/onboard/doctor/auth/skills/hooks/sandbox 等命令

操作二：配置检查（本环境实测，全项通过）

moltis doctor

预期输出: 配置/安全检查项（TOML 有效、无 API key 泄露；数据目录权限 warn 可手动 chmod 700）

操作三：配置向导（首次使用）

moltis onboard

预期输出: 交互式配置（provider/通道/沙箱；人工介入）

操作四：启动网关（默认子命令，常驻进程 + 端口）

moltis gateway

预期输出: 网关启动日志（Ctrl+C 停止；生产用 systemd 托管）

数据与目录

• 配置：~/.config/moltis/（首次运行自动生成）；
• 数据：~/.local/share/moltis 或安装目录 share/moltis/（记忆/会话/通道数据）。

卸载与清理

note: 二进制删除 + 专属配置自动删；数据目录与沙箱镜像手动确认

rm -f /usr/local/bin/moltis
rm -rf ~/.config/moltis
command -v moltis >/dev/null 2>&1 && echo "残留: moltis 仍存在" || echo "moltis removed: OK"

预期输出: moltis removed: OK

手动确认清单（用户数据，不自动删）：

• 数据目录：~/.local/share/moltis 或安装目录 share/moltis/（记忆/会话/通道数据）
• Docker 沙箱镜像：docker images 中 moltis 相关镜像
• 通道 Bot（Telegram/WhatsApp）：随配置删除 token 失效，服务端侧 Bot 可保留

依赖警告

• 版本：[20260830.01, 20260830.01] 锁定（2026-08-31 隔离实测升级：gh-proxy 下载 67.5MB + --version 20260830.01；日期版本滚动，每次升级按同样路径验证）。
• 环境：Linux x86_64；/usr/local/bin 可写；其他平台走对应资产（AppImage/dmg/exe/deb/rpm）。
• 网络：GitHub 直连 3KB/s 超时（实测），必须 gh-proxy（实测 68M/16s）。
• 写面：~/.config/moltis/（专属）+ 数据目录（~/.local/share/moltis）。
• 后台进程：gateway 常驻（端口绑定）；生产用 systemd。
• 共装：判定全部 possible-compatible——moltis 只写 ~/.config/moltis/（专属）+ 数据目录，无共享注册面。

FAQ（常见问题）

• 问：下载很慢/装不上？答：国内直连 GitHub release 资产实测 3KB/s 超时——必须用安装段的 gh-proxy 前缀（实测 68M/16s）；也可用 npm/cargo 镜像构建（备选）。
• 问：装完怎么开始用？答：moltis doctor 检查配置 → moltis onboard 向导配置 provider → moltis gateway 启动。
• 问：gateway 是干嘛的？答：默认子命令 = 常驻网关服务器（端口绑定），对外提供 agent 服务；不用时 Ctrl+C 或 systemd 管理。
• 问：和别的插件冲突吗？答：判定全部 possible-compatible——moltis 只写 ~/.config/moltis/（专属）+ 数据目录，无共享注册面。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。