基于Discord与Modal构建云端AI编程沙箱：低成本弹性架构实践

1. 项目概述：一个将Discord聊天室变成AI编程工坊的“妄想工厂”

如果你和我一样，既想随时随地用上Claude Code这样的AI编程助手，又不想在本地电脑上常驻一个吃资源的进程，或者希望团队能共享一个稳定、隔离的AI编程环境，那么这个名为“SMILE-factory”的项目，绝对值得你花十分钟了解一下。它的核心，我称之为“妄想工厂”（Delulu），是一个精巧的Discord机器人。你只需要在Discord的任意频道里@它，它就能在云端瞬间为你拉起一个专属的、临时的Claude Code编程沙箱，执行完你的任务后自动销毁，而所有的工作区文件和会话状态都会被妥善保存。下次你在同一个对话线程里继续提问，它还能接着上次的上下文继续工作。

这听起来有点像科幻场景，但实现它的技术栈却相当务实和清晰：一个轻量级的Discord Bot作为交互前端，Modal平台提供强大的、按需启动的容器化计算能力，Anthropic的Claude Code作为核心的AI编程引擎。整个架构的精妙之处在于，它将重度的计算负载（运行Claude Code）完全剥离到了云端沙箱，而本地或服务器上只需要运行一个内存占用极低（约50MB）的调度机器人。这意味着你可以用一个每月仅需几美元的VPS（如DigitalOcean最基础的Droplet）来托管这个机器人，就能获得近乎无限的、可随时调用的AI编程算力。

项目原名“SMILE-factory”下其实包含两个子项目，其中活跃的“Delulu”是我们讨论的重点。另一个“LoRA-Instruct”是关于大语言模型微调的早期工作，目前已被归档，它展示了项目作者在AI领域的另一面探索，但今天我们聚焦于更具实用性的Discord机器人。

2. 核心架构与设计哲学：为什么这样设计？

在深入代码之前，理解整个系统的设计思路至关重要。这能帮助你在部署、调试乃至二次开发时，清楚地知道每个环节在做什么，以及为什么这么做。

2.1 核心工作流程拆解

整个系统的交互可以概括为以下几步，我把它比作一个高效的云端餐厅：

1. 你点餐（用户触发）：你在Discord的某个频道里发送一条消息，并@提及这个机器人（比如@CodingBot 帮我写一个Python爬虫）。
2. 餐厅开单（创建会话）：机器人看到你的@消息后，会立即在同一个频道下创建一个新的公开讨论串（Thread），这个讨论串的名字通常就是你的指令摘要。同时，它在自己的内存里为这个讨论串ID注册一个新的“会话”。
3. 后厨开工（调度沙箱）：机器人自己不处理你的请求。它更像一个前台服务员，拿起对讲机，呼叫后厨（Modal平台）：“来一份‘Python爬虫’，送到3号桌（对应讨论串ID的工作区）”。它通过Modal的Python客户端，远程调用一个预先部署好的函数。
4. 名厨掌勺（沙箱执行）：Modal平台收到指令后，瞬间启动一个全新的、干净的容器（沙箱）。这个容器里已经预装了Node.js和Claude Code。沙箱启动后，会将两个关键目录挂载到Modal的持久化存储卷（Volume）上：一个是Claude Code的“家目录”（/vol/claude-home/.claude），里面存放着OAuth认证信息和会话历史；另一个是专属的“工作台”（/vol/workspaces/<讨论串ID>）。接着，沙箱在对应的工作台目录下，执行claude -p --continue命令，将你的问题提交给Claude API。
5. 上菜与收摊（返回与销毁）：Claude Code处理完成后，将结果输出到标准输出（stdout）。沙箱捕获这个输出，将其返回给前台机器人，然后自己“功成身退”——容器被销毁。Modal的计费精确到秒，任务结束即停止计费。
6. 加菜（持续对话）：当你在这个讨论串里回复，想继续追问或修改代码时，你不需要再次@机器人。机器人会监测到这是同一个讨论串内的回复，自动使用claude --continue命令，基于之前保存在Volume里的会话历史和工作区文件，让Claude Code接着上次的上下文继续回答。

关键设计洞察：这种“前台轻量调度 + 后台重型沙箱”的架构，是项目成本与弹性得以平衡的核心。机器人进程极其轻量，可以运行在非常廉价的VPS上。所有昂贵的、动态的计算和AI调用，都发生在按需创建、按秒计费的Modal沙箱中。这比常驻一个拥有强大GPU的服务器要经济得多。

2.2 关键组件与数据流

为了更直观，我们可以抛开复杂的流程图，用一张简单的表格来理解各个组件的职责和数据流向：

数据流总结：

1. 初始化：Claude OAuth凭证通过Modal Secret注入，在第一次运行沙箱时被写入Volume的claude-home。此后，Volume中的副本成为凭证来源，Secret仅作为备份。
2. 请求流：用户@消息 -> Discord -> Bot -> Bot调用Modal函数 -> Modal启动沙箱 -> 沙箱读取Volume中的凭证和工作区 -> 沙箱调用Claude API -> 结果返回给沙箱 -> 沙箱返回给Bot -> Bot回复到Discord讨论串。
3. 状态持久化：所有与会话相关的状态（认证、聊天历史、代码文件）都保存在Modal Volume中，与短暂存在的Bot进程和沙箱容器解耦。因此，即使Bot重启或沙箱新建，只要讨论串ID不变，就能找到对应的工作区和历史，实现无缝继续。

2.3 架构设计的精妙之处与考量

这个设计解决了几个关键问题：

• 安全性隔离：你的Claude OAuth凭证从未到达你托管Bot的VPS。它们只存在于Modal的Secret和Volume中。VPS被攻破，最多损失Discord Bot Token，而无法窃取你的Claude账户。
• 成本优化：Bot作为轻量级调度器，可以24/7运行在低配VPS上。昂贵的AI计算和临时的软件环境（沙箱）仅在需要时按秒计费，用完即焚。
• 状态持久化：通过将HOME环境变量指向Volume上的claude-home，巧妙地将Claude Code的所有状态（包括刷新令牌）持久化。这使得跨多次、离散的沙箱调用维持一个“连续”的Claude会话成为可能。
• 简化部署：Bot容器只需要Python和Modal客户端库，无需安装Node.js或Claude Code CLI，大大降低了宿主机的环境复杂度。

3. 从零开始部署你的“妄想工厂”

理解了原理，我们开始动手搭建。整个过程分为三个主要部分：配置Discord机器人、设置Modal云函数、最后部署Bot主机。我会详细说明每一步的意图和可能遇到的坑。

3.1 第一步：创建并配置Discord机器人

这是机器人与Discord平台通信的凭证。

1. 创建应用：访问 Discord开发者门户 ，点击右上角“New Application”，给它起个名字，比如Delulu Factory。
2. 创建机器人：在应用设置页面的左侧边栏，找到“Bot”选项，点击进入。然后点击“Add Bot”。在弹出的确认框中，选择“Yes, do it!”。
3. 获取并保存Token：在Bot页面，找到“TOKEN”部分，点击“Reset Token”并确认。请立即复制这个Token，它只会显示一次。将其安全保存，这就是后面要用到的DISCORD_BOT_TOKEN。
4. 开启消息内容意图：在Bot页面下方，找到“Privileged Gateway Intents”区域。必须勾选“MESSAGE CONTENT INTENT”。这是因为机器人需要读取频道中@它的消息内容。勾选后点击“Save Changes”。
5. 生成邀请链接：转到左侧边栏的“OAuth2” -> “URL Generator”。
   • 在“Scopes”下，勾选bot。
   • 在“Bot Permissions”下，勾选以下权限（根据你的需求可以调整）：
     • View Channels(查看频道)
     • Send Messages(发送消息)
     • Create Public Threads(创建公开讨论串)
     • Send Messages in Threads(在讨论串中发送消息)
     • Read Message History(读取消息历史)
   • 页面底部会生成一个URL，复制它。
6. 邀请机器人：在浏览器中打开复制的URL，选择你想要添加机器人的服务器，然后点击“Authorize”。完成人机验证后，机器人就会出现在你的服务器成员列表中。

实操心得：妥善保管你的Bot Token。如果泄露，应立即在开发者门户重置。另外，MESSAGE CONTENT INTENT权限是2022年Discord API更新后要求的，如果不开启，机器人将无法读取消息内容，也就无法响应@提及。

3.2 第二步：设置Modal与Claude Code沙箱

这是项目的“计算引擎”部分，所有AI代码执行都发生在这里。

3.2.1 环境准备与Modal认证

首先，确保你的本地环境有Python 3.14+和uv（一个快速的Python包管理器和安装器）。然后进入沙箱项目目录：

cd apps/delulu_sandbox_modal uv sync # 安装依赖 uv run modal setup # 这会打开浏览器，完成Modal账户认证

3.2.2 创建Claude OAuth密钥

这是最关键也最容易出错的一步。我们需要为机器人创建一个独立的Claude Code登录会话，避免干扰你个人电脑上的claudeCLI。

# 使用一个临时目录作为HOME，隔离登录环境 HOME=/tmp/claude-bot-home claude login # 执行后，会打开浏览器，引导你完成Claude（Pro或Max订阅）的OAuth登录流程。 # 登录成功后，凭证会保存在 /tmp/claude-bot-home/.claude/.credentials.json # 将凭证作为Modal Secret创建，命名为 `claude-oauth` uv run modal secret create claude-oauth \ CLAUDE_CREDENTIALS_JSON="$(cat /tmp/claude-bot-home/.claude/.credentials.json)" # 清理临时目录 rm -rf /tmp/claude-bot-home

为什么这么做？沙箱函数启动时，会读取这个Secret，并将其内容写入Volume的/vol/claude-home/.claude/.credentials.json。之后，Claude Code就会使用这个文件进行认证。Secret只在首次或凭证失效需要重置时使用，Volume中的文件才是运行时真正的凭证来源。

3.2.3 （可选但推荐）配置GitHub PAT密钥

项目支持一个/commit命令，允许Claude Code将工作区中的代码变更提交并推送回GitHub仓库。这需要GitHub的Personal Access Token (PAT)。

1. 创建占位符Secret（为了能成功部署）：Modal的Secret.from_name调用要求Secret必须存在。我们可以先创建一个占位符：

   uv run modal secret create github-pat GITHUB_TOKEN=placeholder

2. 生成真正的PAT（后续启用功能时）：

   • 访问 GitHub -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic) 或 Fine-grained tokens。
   • 建议使用Fine-grained token，权限更精细。创建一个新Token，至少需要对你想要推送的仓库有Contents: Read and write权限。
   • 复制生成的Token（以ghp_开头）。

3. 更新Secret：

   uv run modal secret create github-pat GITHUB_TOKEN=ghp_你的真实token --force

   • 可选：你还可以同时设置提交者的作者信息，让提交记录更美观：

     uv run modal secret create github-pat \ GITHUB_TOKEN=ghp_你的真实token \ GIT_AUTHOR_NAME="你的名字" \ GIT_AUTHOR_EMAIL="你的邮箱" \ --force

   注意：--force参数会覆盖同名的现有Secret。

3.2.4 部署沙箱应用到Modal

一切就绪后，从项目根目录部署：

make deploy-modal # 或者进入子目录部署 make -C apps/delulu_sandbox_modal modal-deploy

这个过程会将apps/delulu_sandbox_modal/src/delulu_sandbox_modal/app.py中定义的Modal应用（包括容器镜像、Volume、Secret引用和函数）部署到你的Modal账户下。部署成功后，你会得到一个类似hanl-org/delulu-sandbox-modal的应用名，后续Bot会通过这个名字来远程调用函数。

3.3 第三步：部署Discord Bot主机

Bot主机可以是你的本地电脑（用于开发测试），也可以是一台云服务器（用于7x24小时服务）。

3.3.1 配置Bot环境

首先，复制环境变量模板并填入你的Discord Bot Token：

cd apps/delulu_discord cp .env.example .env # 编辑 .env 文件，将 DISCORD_BOT_TOKEN 的值替换为你之前保存的Token

3.3.2 选择运行方式

方式A：本地运行（测试用）

cd apps/delulu_discord uv run delulu-discord

如果一切正常，你会在终端看到Bot登录成功的日志。现在可以去Discord测试@它了。

方式B：使用Docker运行（推荐用于生产）项目提供了Makefile来简化Docker操作：

# 在 apps/delulu_discord 目录下 make deploy # 这会构建Docker镜像并以容器方式运行 make logs # 查看容器日志

make deploy命令默认会从/root/disco.env读取环境变量，从/root/.modal.toml读取Modal凭证。如果你的文件路径不同，可以覆盖环境变量：

make deploy ENV_FILE=/你的/路径/.env MODAL_TOML=/你的/路径/.modal.toml

3.3.3 部署到DigitalOcean Droplet（生产环境）

对于永久在线的服务，一个廉价的VPS是完美选择。以下是详细步骤：

1. 初始化Droplet：在DigitalOcean创建一个最基础的Ubuntu 24.04 Droplet（$4-6/月，512MB内存足够）。通过SSH登录。
2. 安装基础软件：

   ssh root@<你的Droplet-IP> apt update && apt install -y docker.io git systemctl enable --now docker

3. 克隆代码：

   git clone https://github.com/<你的用户名>/SMILE-factory.git cd SMILE-factory

4. 配置Bot环境文件：

   # 创建Makefile期望的配置文件路径 cat > /root/disco.env <<'EOF' DISCORD_BOT_TOKEN=你的Discord_Bot_Token_在这里 EOF chmod 600 /root/disco.env # 保护Token文件

5. 上传Modal凭证：从你的本地电脑，将Modal认证文件复制到Droplet上。Bot容器需要这个文件来调用Modal函数。

   # 在你的本地终端执行 scp ~/.modal.toml root@<你的Droplet-IP>:/root/.modal.toml

6. 构建并运行Bot容器：

   # 在Droplet的SMILE-factory目录下 make deploy-bot # 这是顶层Makefile的快捷命令，等同于 make -C apps/delulu_discord deploy

7. 验证运行：

   make -C apps/delulu_discord logs

   如果看到Bot成功连接Discord的日志，说明部署成功。容器设置了--restart=unless-stopped，即使服务器重启也会自动运行。

4. 测试、使用与问题排查

部署完成后，是时候检验成果了。

4.1 基础功能测试

1. 将Bot邀请到一个你有权限的Discord频道（例如#general）。
2. 发送一条消息并@Bot，例如：@你的Bot名字 用Python写一个简单的HTTP服务器。
3. 等待约10-30秒（取决于Modal冷启动时间）。Bot应该会：
   • 在你的消息下方创建一个新的公开讨论串（Thread）。
   • 在该讨论串中回复Claude Code生成的结果（代码和解释）。
4. 在同一个讨论串内，直接回复新的指令，例如：现在给它添加一个记录访问日志的功能。Bot会自动使用--continue参数，基于之前的上下文继续生成代码。

4.2 常见问题与排查指南

如果Bot没有反应，可以按照以下步骤排查：

避坑技巧：最棘手的通常是Claude OAuth凭证问题。Modal Volume上的凭证文件可能会因为Claude的刷新令牌机制或未知原因失效。定期检查Bot日志，如果发现认证错误，最干脆的解决办法就是通过Modal CLI (modal volume ls,modal volume rm) 或Web UI删除旧的claude-home数据卷，然后重新创建Secret并触发一次新的Bot调用，让系统重新初始化。

5. 进阶配置与维护

5.1 配置GitHub提交功能

如前所述，配置好github-patSecret后，你可以在Claude Code的对话中使用/commit命令。Bot会调用Modal函数，将当前工作区的变更提交并推送到关联的GitHub仓库。这非常适合将AI生成的代码直接归档或集成到你的工作流中。

安全建议：为Bot创建专用的GitHub机器账户，或者使用Fine-grained token并严格限制其仓库访问范围，避免使用拥有过广权限的PAT。

5.2 利用CI/CD实现自动化部署（GitHub Actions）

项目内置了GitHub Actions工作流，可以实现代码推送后的自动测试和部署，非常专业。

核心流程：

1. CI（持续集成）：当有Pull Request或推送到main分支时，自动运行代码风格检查（Ruff）和测试（Pytest）。
2. CD（持续部署）：当代码合并到main分支后，自动执行：
   • 沙箱部署：在GitHub Runner上使用专用的CI Token，将最新的Modal沙箱函数部署到云端。
   • Bot部署：通过SSH连接到你的Droplet，拉取最新代码，重新构建并重启Bot容器。

一次性设置步骤：

1. 在Droplet上生成SSH部署密钥（在Droplet上执行）：

   ssh-keygen -t ed25519 -f /root/.ssh/disco_deploy -N "" -C "github-actions-disco" cat /root/.ssh/disco_deploy.pub >> /root/.ssh/authorized_keys

2. 在GitHub仓库添加Secrets：
   • DROPLET_HOST: 你的Droplet IP地址。
   • DROPLET_SSH_KEY:私钥/root/.ssh/disco_deploy的全部内容。
   • MODAL_TOKEN_ID和MODAL_TOKEN_SECRET: 在Modal设置页面为CI专门创建的Token。
3. 手动触发测试：在GitHub仓库的Actions页面，找到delulu工作流，点击“Run workflow”进行手动测试。

回滚策略：如果新部署的版本有问题，最安全的方式是使用git revert回退提交并推送到main分支，CI/CD流水线会自动将生产环境回滚到上一个稳定版本。

5.3 本地开发与代码规范

项目使用uv管理依赖，Ruff进行代码检查和格式化，并配置了pre-commit钩子。

• 同步依赖：进入任一子项目目录 (apps/delulu_discord或apps/delulu_sandbox_modal)，运行uv sync。
• 代码检查与格式化：

  make check # 在项目根目录运行，检查两个子项目 make -C apps/delulu_discord lint # 仅对discord bot项目进行lint并尝试自动修复 make -C apps/delulu_discord fmt # 格式化代码

• 启用pre-commit：在本地仓库根目录运行pre-commit install。此后每次git commit，都会自动对暂存的文件进行格式化检查。

6. 项目结构深度解析

了解代码结构有助于你进行定制化开发或故障排查。

SMILE-factory/ ├── apps/ # 核心应用目录 │ ├── delulu_discord/ # Discord Bot (轻量调度器) │ │ ├── src/delulu_discord/ │ │ │ ├── main.py # 入口点，处理Discord客户端事件，实现@提及门控 │ │ │ ├── handlers.py # 消息路由逻辑：创建线程、下载附件、调用调度器、回复结果 │ │ │ ├── session_manager.py # 管理内存中的线程ID到会话的映射，带TTL清理 │ │ │ ├── dispatcher.py # SandboxDispatcher类，封装对Modal远程函数的调用 │ │ │ └── settings.py # 使用Pydantic从环境变量加载配置 │ │ ├── Dockerfile # 构建Bot容器镜像，仅包含Python和必要库 │ │ └── Makefile # 本地开发、构建、部署的命令集 │ │ │ └── delulu_sandbox_modal/ # Modal沙箱函数 (重型执行器) │ └── src/delulu_sandbox_modal/ │ └── app.py # 核心文件！定义Modal App、容器镜像、Volume、Secret和运行Claude Code的函数 │ ├── ARCHITECTURE.md # 详细的设计文档，推荐阅读 └── Makefile # 顶层命令分发器，方便执行跨子项目的操作

定制化开发建议：

• 修改Bot行为：例如，想改变讨论串的命名规则，或添加新的Discord斜杠命令，主要修改apps/delulu_discord/src/delulu_discord/handlers.py。
• 修改沙箱环境：例如，想在沙箱中预装更多系统包（如ffmpeg,graphviz），需要修改apps/delulu_sandbox_modal/src/delulu_sandbox_modal/app.py中的image定义部分，使用.pip_install()或.apt_install()方法。
• 调整资源规格：Modal函数默认的CPU/内存配置可能不适合你的任务。你可以在app.py的@app.function装饰器中调整cpu,memory,gpu等参数。

7. 总结与个人体会

搭建并运行这个“妄想工厂”一段时间后，我最大的感受是它完美诠释了“云原生”思维在个人项目中的应用。它将状态、计算和调度清晰地分离，用最适合的服务处理最适合的任务：Discord负责交互，Modal负责弹性计算和持久化存储，Claude负责AI能力，而一个微不足道的VPS则负责串联一切。

这种架构带来的好处是实实在在的：

• 成本极低：我的Bot运行在一个$6/月的Droplet上，而Modal的计费在我间歇性使用的场景下，每月费用几乎可以忽略不计。
• 维护简单：Bot本身无状态，出了问题直接重启容器就好。最复杂的Claude认证和AI执行环境完全托管在Modal上。
• 体验无缝：在Discord里随时@一下就能开始编程，对话上下文还能保留，这种流畅感是打开本地IDE、启动终端所不能比的。

当然，它也有其适用边界。它不适合需要极低延迟（毫秒级）响应的场景，因为Modal沙箱有冷启动时间。它也更适合代码生成、脚本编写、问题解答这类“任务型”交互，而不是持续的、流式的对话。

如果你是一个喜欢在Discord社区里交流技术的开发者，或者想为你的小团队提供一个共享的、隔离的AI编程环境，这个项目提供了一个非常优雅且高性价比的解决方案。从零开始部署一遍，不仅能获得一个实用的工具，更能深入理解现代云服务如何组合起来解决复杂问题。