1. 项目概述一个为Discord量身定制的Claude智能体运行栈如果你和我一样既想在日常工作的Discord频道里无缝调用Claude这样的强大AI助手又对复杂、臃肿的Bot框架感到头疼那么nanoclaw-discord这个项目可能就是你在找的答案。简单来说它是一个极简、透明的技术栈核心目标就一个让你能在指定的Discord频道里通过一个简单的触发词比如!nano安全、隔离地运行Claude智能体并让它帮你处理各种任务从信息查询到自动化工作流。这个项目的哲学非常吸引我“一个栈一件事足够小到能看懂”。它没有提供眼花缭乱的可选运行时或消息通道而是直接锁定了“Discord作为前端交互界面Docker作为后端执行沙箱”这个黄金组合。这意味着你不需要在YAML配置矩阵里挣扎也不需要担心不同组件间的兼容性问题。整个代码库小到你可以在一杯咖啡的时间里通读一遍理解从消息接收到容器销毁的完整生命周期。这种设计带来的直接好处是极佳的透明度和可控性你知道你的AI助手在做什么以及它是如何做到的。2. 核心架构与设计哲学拆解2.1 为什么是“Discord Docker”的黄金组合在开始动手之前理解作者为何选择这个技术栈至关重要。这并非随意搭配而是经过深思熟虑的权衡。首先Discord作为前端具有天然优势。对于开发者、团队或社区而言Discord已经是日常沟通协作的中心。将AI助手集成于此意味着无需让用户切换上下文到另一个网页或应用交互可以发生在最自然的对话流中。Discord成熟的机器人APIdiscord.js提供了稳定的事件监听如MessageCreate和丰富的消息交互能力足以支撑一个智能体的基础通信需求。项目选择只支持Discord而非抽象出一个“通道提供商”层是为了避免通用化带来的复杂性让代码专注于做好一件事。其次Docker作为运行时是安全与可移植性的基石。Claude智能体本质上是一个可以执行代码、访问文件、进行网络请求的“活”的进程。直接在宿主机上运行它存在巨大风险。Docker容器提供了轻量级的隔离环境每个任务都在一个全新的、短暂的容器中执行任务结束容器即销毁。通过精确控制挂载卷-v参数你可以严格限定智能体能访问的文件范围例如只让它看到某个项目目录而无法触及你的SSH密钥或系统文件。这种“安全隔离”的设计是让AI助手从玩具变为可信赖工具的关键一步。项目强调只支持Docker而非其他容器运行时是为了保证在macOS和Linux上拥有一致、简单的部署体验。2.2 极简的单进程模型与数据流nanoclaw-discord的架构清晰得令人愉悦完全摒弃了微服务、消息队列等现代分布式系统的复杂性。整个系统就是一个单一的Node.js进程在运行我称之为“主机进程”。这个主机进程同时扮演了多个角色Discord客户端通过discord.js库保持与Discord服务器的长连接监听指定频道中的消息事件。消息路由器当在已注册的频道中检测到触发词如!nano时它会解析消息确定目标频道即“群组”。任务调度器管理定时任务如“每天上午9点发送报告”在预定时间触发容器执行。容器编排器这是核心。它负责为每次请求无论是即时消息还是定时任务动态组装Docker命令。这包括基于频道ID确定对应的数据目录groups/group_id/。构建挂载参数将该频道的专属目录包含其CLAUDE.md记忆文件和允许访问的数据映射到容器内。从.env文件中筛选出允许传递给容器的环境变量如ANTHROPIC_API_KEY。执行docker run命令启动一个包含Claude Agent SDK的临时容器并将用户消息作为输入传入。日志与状态记录器将任务执行历史和结果记录到SQLite数据库中便于后续查询或调试。数据流可以概括为Discord用户消息 - discord.js事件 - 主机进程路由 - 组装Docker命令 - 启动临时容器 - 容器内Claude处理 - 响应写回容器输出 - 主机进程捕获输出 - 通过discord.js发送回复消息到原频道。整个过程是同步或短时异步的没有常驻的AI服务进程资源使用非常节俭。2.3 “安全隔离”与“单用户”设计的内涵项目的安全模型值得深入探讨。它并非宣称“绝对安全”而是通过架构设计将风险降至可管理和可理解的水平。安全隔离主要体现在三个方面文件系统隔离每个Discord频道群组在宿主机上有独立的groups/channel_id目录。当该频道的请求到来时只有这个目录会被挂载到Docker容器中。容器内的进程无法访问宿主机的其他任何文件。这意味着你可以安全地将#project-alpha频道的AI助手指向你的代码库而不用担心它通过../../之类的路径爬取到你#personal-finance频道下的敏感预算表格。环境隔离容器拥有一个全新的、纯净的进程环境。只有显式声明的环境变量在src/container-runner.ts中定义的白名单会从宿主的.env文件传递进去。你的数据库密码、其他服务的令牌等只要不在白名单内就对AI不可见。生命周期隔离每个任务都是一个独立的容器实例。任务完成后容器立即停止并被移除。任何在任务执行过程中产生的临时状态或文件改动除非写入挂载卷都会随着容器的消失而消失不会留下“脏”状态影响下一次任务。“为单用户设计”是另一个重要哲学。这不是一个面向企业多租户的SaaS平台。它鼓励你fork这个仓库然后根据你自己的工作流进行深度定制。所有的配置——哪些频道被注册、每个频道的指令是什么、有什么技能——都通过代码和Markdown文件来定义而不是通过一个复杂的Web管理界面。这种做法的好处是你的整个AI助手配置是可版本控制的、可审查的、可复现的。当你需要迁移服务器或重建环境时一切尽在掌控之中。3. 从零开始的详细部署与配置指南3.1 前期环境准备与依赖安装让我们开始动手。首先确保你的系统满足以下要求操作系统macOS 或 Linux包括WSL2。这是硬性要求因为Docker Desktop在这两个平台上的支持最为一致。Node.js版本20或更高。建议使用nvmNode Version Manager来安装和管理Node版本这样可以轻松切换且不影响系统全局环境。Docker Desktop确保Docker守护进程正在运行。在终端执行docker --version和docker run hello-world来验证安装和运行是否正常。Claude Code这是Anthropic官方提供的IDE插件项目强烈推荐使用它来进行初始化和后续的代码修改。它深度集成在编辑器中能理解项目上下文并提供引导。注意虽然项目提到可以用Claude Code引导但了解底层步骤能让你在遇到问题时从容应对。以下是我手动执行的“幕后”步骤与Claude Code的引导结果一致。第一步获取代码git clone https://github.com/jaypyles/nanoclaw-discord.git cd nanoclaw-discord此时项目目录结构大致如下非常简洁nanoclaw-discord/ ├── src/ # 核心TypeScript源代码 │ ├── index.ts # Discord主客户端和路由 │ ├── container-runner.ts # Docker容器生成器 │ └── ... ├── groups/ # 各频道/群组的独立空间 │ └── main/ # “主频道”的默认目录 │ └── CLAUDE.md # 主频道的长期记忆和指令 ├── data/ # 运行时数据数据库、注册信息 ├── container/ # Docker容器相关文件 │ ├── Dockerfile # 构建Agent运行环境的镜像 │ └── skills/ # 自定义技能存放处 ├── .env.example # 环境变量模板 └── package.json # Node.js项目依赖3.2 核心配置三步曲Bot、API与频道配置的核心是三个关键信息Discord Bot令牌、Anthropic API密钥以及决定Bot在哪个频道生效。1. 创建并配置Discord Bot访问 Discord开发者门户 点击“New Application”为你的AI助手起个名字。在左侧边栏进入“Bot”页面点击“Reset Token”生成一个新的令牌Token。务必立即复制并妥善保存它只显示一次这就是你的DISCORD_TOKEN。在同一个Bot页面向下滚动到“Privileged Gateway Intents”。必须开启“MESSAGE CONTENT INTENT”。这是因为Bot需要读取频道消息的具体内容来识别触发词!nano默认情况下Discord出于隐私考虑禁止Bot读取消息内容必须显式开启此权限。接下来需要将Bot邀请到你的服务器。进入“OAuth2” - “URL Generator”。在“Scopes”中选择bot在“Bot Permissions”中根据需求选择权限。最低限度需要“Send Messages”, “Read Message History”以及如果你希望Bot能管理定时任务可能需要“Manage Messages”。生成链接后用浏览器打开选择你的服务器即可邀请。2. 设置Anthropic API密钥你需要一个有效的Anthropic API密钥来调用Claude模型。前往 Anthropic控制台 创建密钥。复制这个密钥它将作为ANTHROPIC_API_KEY。3. 配置环境变量与频道注册项目使用.env文件管理敏感配置。复制模板文件并编辑cp .env.example .env用你喜欢的编辑器打开.env文件填入刚才获取的信息DISCORD_TOKEN你的Discord_Bot令牌 ANTHROPIC_API_KEY你的Anthropic_API密钥其他环境变量如CLAUDE_MODEL可选默认为claude-3-5-sonnet-latest可以按需调整。接下来是频道注册这是控制Bot响应范围的关键。Bot不会响应所有频道只响应在data/registered_groups.json中明确注册的频道。你需要获取目标频道的Discord频道ID一串数字。在Discord设置中开启“开发者模式”。右键点击你想添加的频道选择“复制频道ID”。 首先你需要注册一个“主频道”拥有管理权限。将频道ID填入data/registered_groups.json{ groups: { 你的主频道ID数字: { name: main, isMain: true } } }isMain: true表示这个频道可以执行管理命令如注册其他频道、列出任务等。3.3 构建Docker镜像与启动应用配置好后我们需要构建运行Claude Agent的Docker镜像并启动Bot应用。安装Node依赖并构建TypeScriptnpm install npm run build # 这会编译src/下的TypeScript代码到dist/目录构建Docker镜像docker build -t nanoclaw-agent -f container/Dockerfile .这个过程会下载一个包含Node、Claude Agent SDK等必要组件的轻量级Linux镜像并将其标记为nanoclaw-agent。后续每次请求都会基于这个镜像启动新容器。启动Botnpm start如果一切顺利你将在终端看到Bot登录成功的提示。现在前往你注册的“主频道”尝试发送!nano hello。你应该会收到Claude的回复。恭喜你的私有AI助手已经上线了4. 深入使用技能、记忆与自动化任务4.1 理解并定制“群组记忆”CLAUDE.mdnanoclaw-discord一个精妙的设计是为每个频道群组维护独立的CLAUDE.md文件位于groups/channel_id/目录下。这个文件不是普通的配置而是Claude Agent的长期记忆和核心指令集。当某个频道的请求被处理时该频道对应的CLAUDE.md文件会作为系统提示词System Prompt的一部分被注入到容器中。这意味着你可以为不同的频道设定完全不同的人格、知识和任务范围。例如你的#coding-help频道的CLAUDE.md可能是这样的# 编程助手模式 你是一个专注于Python和Web开发的专家助手。你的语气直接、专业专注于解决问题。 请始终优先考虑代码的清晰性和可维护性。 你可以访问当前目录下的src/文件夹中的源代码。 本频道讨论的所有内容都是关于“A项目”的。而你的#weekly-planning频道的CLAUDE.md则可能是# 项目经理模式 你是一个高效、有条理的项目协调员。擅长将模糊的需求分解为具体的行动项。 请用表格形式总结讨论出的任务包含负责人、截止日期和状态。 你可以读取plans/目录下的历史计划文档作为参考。你可以直接编辑这些CLAUDE.md文件来塑造不同频道中AI的行为。这也是项目“AI-Native”理念的体现你通过自然语言编辑Markdown来“编程”你的助手而不是填写复杂的JSON表单。4.2 扩展能力添加自定义技能Skills技能Skills是扩展AI助手能力的核心机制。一个技能本质上是一个Markdown文件描述了如何让Claude使用一个新的工具或API。项目内置了一些基础能力如文件读写、网络搜索但你可以轻松添加更多。假设你想让助手能通过Gmail发送邮件创建技能描述文件在container/skills/目录下创建一个新文件例如gmail-api.md。内容大致如下# Gmail API Skill The assistant can send emails via the Gmail API. ## Setup 1. Create a Google Cloud Project and enable the Gmail API. 2. Create OAuth 2.0 credentials (Desktop App type) and download the credentials.json. 3. Place credentials.json in the groups directory (e.g., groups/main/). ## Usage When the user asks to send an email, the assistant can use the pre-authorized Gmail client (available as gmailClient in the container context) to send messages.这个文件是给项目维护者也就是你和Claude Code看的用于理解如何设置这个技能。实现技能逻辑技能的实际功能需要在Docker容器内实现。这通常意味着你需要修改container/Dockerfile添加必要的软件包如Google API客户端库并可能修改容器启动脚本将OAuth凭证注入容器环境并在Claude Agent的上下文中提供一个可用的gmailClient对象。更新群组记忆最后你需要在需要使用该技能的频道的CLAUDE.md文件中添加一条说明告知AI助手它现在拥有这个新能力。例如在groups/main/CLAUDE.md末尾加上## Available Skills - File system access within the mounted directory. - Web search and fetch. - **Send emails via Gmail API.** (Use gmailClient to send. Recipient, subject, and body are required.)这个过程需要一些开发投入但它展示了系统的可扩展性。社区贡献的技能包可以大大丰富助手的能力。4.3 实现工作流自动化定时任务Scheduled Tasks除了即时响应消息nanoclaw-discord的另一个强大功能是定时任务。你可以让AI助手在特定时间自动执行任务并将结果发送到Discord频道。定时任务的管理是通过在主频道向Bot发送指令完成的。其底层原理是主机进程中的task-scheduler.ts模块使用了一个轻量级调度库如node-cron将任务配置持久化到SQLite数据库并在预定时间触发容器执行。创建定时任务 在主频道发送如下格式的指令!nano every weekday at 9:30 AM, check the project status dashboard and post a summary in this channel.Bot会解析这条自然语言指令将其转换为一个cron表达式例如30 9 * * 1-5并保存到数据库中。每天上午9:30系统就会自动启动一个容器执行“检查仪表板并总结”的任务并将结果发送回频道。管理任务 你可以使用一系列管理命令!nano list all scheduled tasks列出所有已注册的定时任务及其状态活跃/暂停。!nano pause the “morning report” task暂停名为“morning report”的任务。!nano resume task [task_id]恢复某个任务。定时任务非常适合用于日常简报、数据监控、定期报告生成等重复性工作将AI从被动的问答工具转变为主动的自动化代理。5. 运维、调试与安全实践实录5.1 日常运维与监控项目采用单进程模型运维相对简单。在生产环境长期运行时我建议采取以下措施使用进程管理器不要直接使用npm start。使用pm2或systemd来管理Node进程实现崩溃自动重启、日志轮转和开机自启。# 使用pm2的例子 npm install -g pm2 pm2 start dist/index.js --name nanoclaw-bot pm2 logs nanoclaw-bot # 查看日志 pm2 save pm2 startup # 设置开机启动日志管理应用的日志会输出到控制台。确保通过进程管理器或Docker的日志驱动将其收集到集中日志系统如journald、syslog或云日志服务中方便排查问题。关键的日志事件包括Bot登录成功、收到消息、启动容器、容器执行结果成功/失败、定时任务触发。资源监控虽然单个容器很轻量但频繁的任务或并发请求可能会消耗资源。监控宿主机的内存、CPU和磁盘I/O。特别注意Docker的磁盘使用情况因为停止的容器和未清理的镜像会占用空间。可以设置一个定期清理的cron任务docker system prune -af --volumes谨慎使用会清理所有未使用的资源。5.2 问题诊断与调试技巧即使设计再简洁运行时也难免遇到问题。以下是我在实践中总结的排查路径问题一Bot不响应消息。检查1Bot是否在线在终端查看应用日志确认没有崩溃并且有“Ready!”之类的登录成功消息。在Discord服务器成员列表中确认Bot的在线状态。检查2频道是否已注册确认你发送消息的频道ID已经在data/registered_groups.json中。使用!nano list groups命令在主频道来查看已注册列表。检查3触发词是否正确默认触发词是!nano前面不能有其他字符。检查是否拼写错误或者消息是否以触发词开头。检查4权限是否足够确认Bot在该频道拥有“查看频道”、“发送消息”和“读取消息历史”的权限。尤其是在新创建的频道可能需要重新邀请Bot或调整频道权限。问题二容器启动失败或任务执行出错。查看容器日志这是最直接的调试信息。当任务执行时主机进程会打印容器的标准输出和错误。在应用日志中寻找Container stdout:和Container stderr:部分。检查Docker镜像确认nanoclaw-agent镜像是否存在且构建正确。可以手动运行一个测试容器docker run --rm -it nanoclaw-agent /bin/bash看看能否进入容器。检查挂载权限确保宿主机上groups/channel_id/目录对Docker守护进程通常是root或docker用户是可读的。权限问题可能导致容器内无法访问挂载的文件。检查API密钥如果错误信息提到“Authentication”或“Invalid API Key”请检查.env文件中的ANTHROPIC_API_KEY是否正确以及是否传递到了容器内检查src/container-runner.ts中的环境变量白名单。问题三Claude没有按照CLAUDE.md的指令行动。确认文件已加载在CLAUDE.md的开头加入一条显式的测试指令如“每次回复的第一句话必须是‘这是测试模式’”。如果这条指令没生效说明文件可能未被正确读取。检查文件路径和格式确认CLAUDE.md文件位于正确的groups/channel_id/目录下并且是有效的UTF-8编码的Markdown文件没有语法错误。指令冲突CLAUDE.md中的指令可能会与Claude Agent SDK的默认指令或其他技能的描述发生冲突。尝试简化CLAUDE.md的内容逐步添加指令以定位问题。5.3 安全加固与最佳实践虽然项目本身提供了容器隔离但作为部署者你还需要在更高层面考虑安全。最小权限原则Discord Bot权限在邀请Bot时只授予它完成功能所必需的最小权限。例如如果不需要管理消息就不要勾选Manage Messages。文件系统挂载在src/container-runner.ts中仔细审查buildMounts函数。确保只挂载必要的目录。绝对不要将宿主机根目录/或家目录~挂载进去。环境变量同样在container-runner.ts中ALLOWED_ENV_VARS数组定义了传递给容器的环境变量白名单。只将AI完成任务所必需的密钥如ANTHROPIC_API_KEY加入白名单切勿传递PATH,HOME, 或其他包含敏感信息的变量。网络隔离默认情况下容器可以访问外网以便Claude调用API和进行网络搜索。如果你希望完全禁止容器访问网络可以在docker run命令中添加--network none参数。但这会使其无法调用Claude API因此不实用。一个折中方案是使用防火墙规则限制容器只能访问api.anthropic.com等必要的出站地址。密钥管理永远不要将.env文件提交到版本控制系统Git。确保.gitignore文件中包含.env。在生产服务器上考虑使用更安全的密钥管理服务如AWS Secrets Manager、HashiCorp Vault或至少使用操作系统级别的环境变量而不是文件。定期更新定期拉取项目更新以获取安全补丁和功能改进。定期重建Docker镜像docker build ...以更新底层操作系统和Node.js的依赖包修复已知漏洞。审计与监控定期查看SQLite数据库data/db.sqlite中的runs表这是所有任务执行的历史记录。检查是否有异常的任务、过长的运行时间或频繁的失败。监控Docker守护进程的日志关注是否有异常的容器创建模式。