deploy-moltbot-to-fly

Deploy Moltbot to Fly.io 是一份面向开发者的详尽部署指南，专注于将 Moltbot（Clawdbot）AI 助手服务部署至 Fly.io 云平台。该技能通过分阶段式教程，指导用户完成从环境准备、应用配置、持久化存储设置到设备配对的全流程，确保用户能够在云端建立稳定运行的智能代理网关。

核心用法涵盖五个关键阶段：首先是克隆代码库并生成安全网关令牌；其次创建 Fly.io 配置文件（fly.toml），设置持久化卷挂载与环境变量；第三阶段通过 Fly CLI 完成应用部署；第四阶段通过 SSH 进入实例创建 JSON 配置文件，配置网关认证与 AI 模型参数；最后完成 DNS 解析与设备配对授权，实现通过 Web UI 安全访问。整个流程强调令牌的双重验证机制（环境变量与配置文件必须一致）以及状态目录的持久化配置。

显著优点在于其极致的实操性与完整性。文档不仅提供生产级的配置模板（如推荐 2GB 内存、shared-cpu-2x 实例规格），还包含详尽的故障排查章节，覆盖网关令牌不匹配、DNS 解析失败、配置验证错误等常见场景。特别值得一提的是其对安全细节的重视，明确要求通过 Fly Secrets 管理 API 密钥，避免敏感信息硬编码，并提供设备配对的自动化脚本，大幅降低了手动配置门槛。

潜在局限性主要体现在平台依赖与手动操作复杂度上。该指南高度依赖 Fly.io 特定的基础设施（如 fly.toml 格式、Fly CLI 工具），迁移至其他云平台需要大量配置重写。此外，设备配对流程需要用户通过 SSH 执行 Node.js 脚本，对非技术用户存在一定门槛。作为 T3 级社区来源项目，其长期维护稳定性与企业级支持保障相对有限。

适合的目标群体包括具备基础 DevOps 知识的开发者、需要自托管 AI 助手的技术团队，以及希望在 Fly.io 上快速验证 Moltbot 功能的早期采用者。对于追求数据主权、需要将 AI 代理部署至私有云环境的用户尤为适用。

使用该技能可能存在的常规风险包括：配置错误导致的网关认证失效（如令牌不匹配）、持久化卷未正确挂载引发的数据丢失、以及 Fly.io 平台本身的依赖性风险。用户需特别注意妥善保管生成的网关令牌，避免在 URL 中明文传输时泄露。建议在生产环境部署前，充分测试配置文件的 JSON 语法有效性，并建立定期备份机制以防止状态数据丢失。

核心用法

本 Skill 是一份完整的 Moltbot（Clawdbot）云部署操作手册，面向希望在 Fly.io 平台自托管 AI Agent 网关的用户。文档采用分阶段式结构：

1. 环境准备 — 安装 Fly CLI、获取 API Key、生成 Gateway Token
2. Fly 配置 — 编写 fly.toml，配置持久化卷（1GB）、环境变量（STATE_DIR、NODE_OPTIONS）、进程启动参数（--bind lan 关键）
3. 密钥注入 — 通过 fly secrets set 注入 ANTHROPIC_API_KEY、OPENAI_API_KEY 及 CLAWDBOT_GATEWAY_TOKEN
4. 部署与验证 — 执行 fly deploy，观察日志确认 Gateway 监听状态
5. 配置文件创建 — SSH 进入实例，在 /data 目录写入 moltbot.json，确保 auth.mode 为 token 且与 env 变量一致
6. 设备配对 — 浏览器访问带 token 的 URL，触发配对请求后，通过 SSH 执行 Node.js 脚本完成设备授权
7. 故障排查 — 涵盖 Token 不匹配、DNS 未解析、Config 验证错误、内存不足等典型问题

显著优点

• 步骤详尽可复现：从克隆仓库到最终 Web UI 连通，每一步均有命令行示例和预期输出，降低新手试错成本
• 安全最佳实践嵌入：强调 Token 双端一致（env + config）、secrets 管理、HTTPS 强制、最小权限部署
• 生产级配置参数：明确 2GB 内存下限、--bind lan 网络绑定、http_service 新格式等易踩坑点
• 故障排查体系化：提供 7 类典型问题的症状-诊断-修复闭环，含"核弹级"重建方案
• 来源可信：源自 GitHub 组织 clawdbot 官方仓库，经 CLS 认证扫描确认零威胁

潜在缺点与局限性

• 无可执行代码：纯 Markdown 指南，用户需手动复制粘贴执行，无自动化脚本封装，易因字符截断或路径错误导致失败
• Fly.io 平台锁定：配置深度绑定 Fly 的 fly.toml、flyctl CLI 及特定网络模型（Anycast + 内部代理），迁移至 AWS/GCP 需重写配置
• Token 管理手动化：设备配对需 SSH 进入实例执行 Node.js 代码片段，无 CLI 原生支持，批量部署场景效率低
• 资源成本未优化：默认推荐 shared-cpu-2x + 2GB RAM，对轻量个人用户可能存在成本冗余
• DNS 传播等待：文档提示 2-5 分钟 DNS 生效，但实际可能因 CDN 边缘节点更长，缺乏主动探测命令

适合人群

• 技术型个人开发者：具备 Linux/CLI 基础，熟悉容器化部署概念，愿意动手调试配置
• 小团队 DevOps：需要为团队内部搭建私有 AI Agent 网关，优先选择 Fly.io 托管
• Moltbot/Clawdbot 早期用户：已了解产品架构，寻求官方推荐的标准化部署路径
• 安全敏感场景：重视数据主权，拒绝 SaaS 托管，倾向自托管 + Token 认证模式

常规风险

| 风险类型 | 描述 | 缓解建议 |

|---------|------|---------|

| Token 泄露 | Gateway Token 在 URL 中明文传输（`?token=`），可能被浏览器历史/日志记录 | 使用一次性浏览器隐私模式，部署后及时清理历史记录 |

| SSH 权限过大 | 设备配对需 SSH 进入生产环境执行代码，误操作可能影响运行态 | 限制 SSH 访问 IP，配对后立即撤销 SSH 会话 |

| Secret 旋转不便 | Fly secrets 更新需重新部署，非热更新，密钥泄露响应存在窗口期 | 定期轮换 API Key，监控 Fly Dashboard 异常流量 |

| 持久化卷误删 | `fly apps destroy` 会连带删除 volume，配置/设备数据不可逆丢失 | 定期备份 `/data` 目录，使用 `fly volumes snapshots` |

| 依赖外部脚本 | 安装阶段使用 `curl | sh` 模式，若 fly.io 域名被劫持存在供应链风险 | 手动下载脚本校验哈希后再执行 |