1. 项目概述一个为个人工作流深度定制的AI助手如果你和我一样每天泡在Discord里和团队沟通同时又重度依赖各类大语言模型来处理信息、生成内容那你肯定也想过能不能有一个助手就住在Discord里能记住我的习惯按我的规则行事还能帮我处理些定时任务今天要聊的Clawcord就是这样一个“小而美”的解决方案。它不是那种功能庞杂、需要复杂配置的通用机器人而是一个高度聚焦、代码清晰、完全围绕你个人工作流打造的AI伙伴。它的核心设计哲学非常明确Discord负责输入输出OpenRouter提供“大脑”。你不用在十几个LLM后端里做选择也不用通过插件市场去集成Discord——这些开箱即用。整个项目就是一个单一的进程代码量不大但五脏俱全。你可以把它理解为你专属的、可编程的“数字同事”它通过你在Discord里它或者私聊来接收指令然后调用OpenRouter API背后可以是GPT-4、Claude或者任何免费/隐匿模型来思考并执行整个过程的数据和规则都保存在你本地仓库的Markdown文件里完全可控。我花了些时间部署和深度使用发现它特别适合需要高频、个性化AI交互的场景。比如你可以让它总结某个频道的近期讨论记住你偏好用24小时制和时间区间甚至让它每天早上9点自动检查某个API状态并汇报。接下来我会从设计思路、部署实操、核心功能定制到深度调优完整拆解这个项目并分享我踩过的一些坑和独家优化技巧。2. 核心设计思路与架构解析2.1 为什么是“Discord OpenRouter”这个组合很多AI助手项目试图做一个“万能插座”支持Slack、Telegram、Discord、微信等所有平台以及OpenAI、Anthropic、Google等所有模型提供商。这听起来很美好但带来的结果是代码复杂度急剧上升配置项多如牛毛最终变成一个难以理解和维护的“巨无霸”。Clawcord反其道而行之它坚定地选择了单一输入通道Discord和单一模型网关OpenRouter。这个选择背后有深刻的实用性考量。首先Discord的机器人生态成熟消息、回复链、线程、私信、Slash命令等API非常完善足以构建丰富的交互场景。其次OpenRouter作为一个聚合平台其价值在于“一个API密钥访问几乎所有主流模型”。这意味着你无需为GPT-4、Claude、Gemini等分别申请密钥、处理不同的计费方式和API格式。你只需要在OpenRouter上充一次值或用免费额度然后在Clawcord的.env文件里改一个OPENROUTER_MODEL变量就能在“免费隐匿模型”和“付费高性能模型”之间无缝切换。这种设计极大地简化了技术栈让开发者可以专注于核心功能——即如何让AI更好地理解并服务于你的工作流。注意选择OpenRouter也意味着你的所有AI请求都会经过它的服务器。虽然OpenRouter信誉良好但如果你处理的是高度敏感的商业机密这一点需要纳入考量。对于绝大多数个人和团队协作场景其便利性远大于潜在风险。2.2 “无界面”配置与“对话式”管理哲学Clawcord另一个颠覆性的设计是彻底抛弃了图形化的控制面板Dashboard。你没有一个Web页面去点击配置行为规则、查看记忆库或管理定时任务。所有的配置都通过两种方式完成直接编辑Markdown文件项目根目录下的agent-core/文件夹里BEHAVIOR.md、MEMORY.md、SCHEDULE.md、COMMANDS.md这几个文件就是机器人的“大脑”。你用文本编辑器修改它们机器人重启或下次响应时会读取并应用。直接告诉机器人你可以通过对话来管理它。例如你它并说“记住我更喜欢用中文回复并且讨厌使用表情符号。” 机器人内部会调用behavior_editor工具将这条规则结构化后写入BEHAVIOR.md。同样你可以问它“我让你记住过哪些关于项目X的事情” 它会调用memory_editor工具查询并返回结果。这种“无界面”和“对话式”管理初看可能觉得不够直观但用久了会上瘾。它迫使你将配置视为代码事实上就是Markdown文件便于版本控制Git。同时通过自然语言管理AI助手本身也是一种非常“AI原生”的体验降低了使用门槛。整个系统的状态完全由这几个文本文件定义没有外部数据库迁移和备份极其简单。2.3 单进程架构与模块职责Clawcord采用单进程架构所有功能消息监听、AI生成、工具调用、定时任务都在同一个Node.js或Bun进程中运行。这避免了微服务带来的部署复杂性和网络开销使得调试和理解代码变得非常容易。以下是核心模块的职责划分src/index.ts这是程序的入口和Discord客户端。它负责登录Discord、监听消息事件on(‘messageCreate’)。当收到一条机器人的消息或私信时它会收集消息的上下文包括整个回复链然后交给AI模块处理。src/ai/generate-reply.ts这是AI响应的“发动机”。它接收来自index.ts的对话上下文然后加载当前的行为规则BEHAVIOR.md和记忆MEMORY.md将这些信息作为系统提示词的一部分连同用户消息一起发送给OpenRouter API。同时它管理着所有可用的“工具”Tools比如编辑记忆、管理日程等。如果AI在思考后决定调用某个工具这个模块会执行工具函数并将结果返回给AI最终由AI组织成自然语言回复。src/ai/tools/这个目录下存放着一个个具体的工具函数它们是机器人能力的扩展。例如behavior_editor.ts: 用于增删改查行为规则。memory_editor.ts: 用于管理长期记忆。schedule_editor.ts: 用于管理定时任务。commands_registry.ts: 用于管理自定义命令文档。skills_reader.ts: 用于读取外部定义的技能Skills。http_fetch.ts,get_time.ts: 提供基础的HTTP请求和获取时间功能。bash_exec.ts:一个需要谨慎启用的危险工具允许AI执行bash命令默认关闭。src/ai/schedule-runner.ts这是一个独立的循环定期检查SCHEDULE.md文件中定义的任务如果到了执行时间就会触发执行通常是调用AI生成内容然后发送到指定Discord频道。这种清晰的职责分离使得如果你想增加一个新功能比如让机器人能查询数据库你只需要在tools目录下创建一个新的工具文件并在generate-reply.ts中注册它即可无需改动核心的消息流逻辑。3. 从零开始的完整部署与配置指南3.1 环境准备与依赖安装Clawcord官方推荐使用Bun作为JavaScript运行时因为它启动速度快且内置了包管理、测试运行器等功能与这个轻量级项目很搭。当然你也可以使用Node.js 20版本但需要手动调整一些脚本比如bun命令要换成node或npm run。第一步获取项目代码打开你的终端找一个合适的目录克隆项目。我建议你直接Fork原仓库到自己的GitHub账户下然后克隆你自己的Fork这样方便后续自定义修改和提交。git clone https://github.com/你的用户名/clawcord.git cd clawcord第二步安装Bun如果尚未安装如果你用的是macOS或Linux安装Bun非常简单# 使用官方安装脚本 curl -fsSL https://bun.sh/install | bash安装完成后重启你的终端运行bun --version确认安装成功。对于Windows用户官方建议使用WSL2来获得最佳的开发体验。第三步安装项目依赖进入项目目录后运行以下命令。Bun会读取package.json和bun.lockb文件快速安装所有必要的依赖包主要是discord.js和ai-sdk/openrouter。bun install这个过程通常很快。如果遇到网络问题可以考虑配置镜像源。3.2 关键平台配置Discord与OpenRouter这是部署过程中最关键的一步需要你在两个第三方平台进行操作。1. 配置Discord应用与机器人访问 Discord开发者门户 点击“New Application”为你的机器人起个名字比如“MyClawcord”。进入创建好的应用在左侧找到“Bot”选项卡。点击“Reset Token”生成一个新的令牌Token并立即复制保存。这个DISCORD_TOKEN是机器人连接Discord的密码一旦离开页面就无法再次查看。在“Privileged Gateway Intents”下务必勾选“Message Content Intent”。这是为了让机器人能够读取消息内容否则它无法看到你它的指令。接下来需要获取DISCORD_CLIENT_ID和DISCORD_GUILD_ID。DISCORD_CLIENT_ID在开发者门户的“General Information”页面就能找到就是“Application ID”。DISCORD_GUILD_ID你需要将机器人邀请到你的某个Discord服务器Guild进行测试。在“OAuth2” - “URL Generator”页面在“Scopes”下勾选bot在“Bot Permissions”下根据需求勾选权限至少需要“Send Messages”, “Read Message History”等。然后会生成一个邀请链接用这个链接将机器人添加到你的服务器。添加成功后在Discord客户端中右键点击你的服务器图标 - “Copy ID”你需要先开启开发者模式设置 - 高级 - 开发者模式复制下来的就是DISCORD_GUILD_ID。2. 获取OpenRouter API密钥访问 OpenRouter官网 注册并登录。在仪表板Dashboard页面你可以找到你的API密钥。点击“Copy”复制它。OpenRouter提供了免费的额度供你开始使用。你可以在“Models”页面浏览所有可用的模型包括标注为“Free”或“Stealth”的模型。记下你感兴趣的模型ID例如google/gemini-2.0-flash-exp:free或mistralai/mistral-7b-instruct:free。3.3 环境变量配置与首次运行项目使用.env文件来管理所有敏感和可变的配置。# 复制环境变量示例文件 cp .env.example .env # 使用你喜欢的编辑器如nano, vim, VS Code编辑.env文件 code .env打开.env文件后你会看到如下内容将上一步获取的信息填入# Discord配置 DISCORD_TOKEN你的Discord机器人令牌 DISCORD_CLIENT_ID你的Discord应用客户端ID DISCORD_GUILD_ID你的Discord服务器ID # OpenRouter配置 OPENROUTER_API_KEY你的OpenRouter API密钥 # 模型设置默认是openai/gpt-4o-mini你可以改为免费模型 OPENROUTER_MODELopenai/gpt-4o-mini # 可选启用Bash工具危险默认关闭 ENABLE_BASH_TOOLfalse重要提示对于OPENROUTER_MODEL如果你只是想先测试而不想花钱强烈建议将其设置为一个免费模型例如google/gemini-2.0-flash-exp:free。你可以在OpenRouter的模型列表页面筛选“Free”来找到最新的免费模型。注册Slash命令并启动机器人Clawcord支持Slash命令如/ping但需要向Discord注册。# 注册Slash命令到你的Discord服务器 bun run register如果注册成功终端会提示“Registered commands successfully”。现在启动机器人# 开发模式启动支持热重载如果你修改了代码 bun run dev # 或者生产模式启动 bun run start如果一切顺利你会在终端看到机器人登录成功的提示。现在转到你的Discord服务器在任意频道你的机器人并发送一条消息例如“MyClawcord 你好”你应该能收到它的回复恭喜你的个人AI助手已经上线了。4. 核心功能深度定制与实战应用4.1 行为规则BEHAVIOR.md塑造机器人的“性格”agent-core/BEHAVIOR.md是机器人的“人格设定集”。它不是一个普通的Markdown文件而是采用了一种叫做**JSONLJSON Lines**的格式即每一行都是一个独立的JSON对象。这种格式既便于机器解析也便于人类阅读和编辑。一个典型的行为规则条目长这样{id: rule_001, enabled: true, category: communication_style, description: Always respond in Traditional Chinese Mandarin., content: You must respond in Traditional Chinese Mandarin for all queries, regardless of the users input language.}id: 规则唯一标识符。enabled: 是否启用该规则。category: 规则分类如communication_style,formatting,constraints等方便管理。description: 规则的简短描述。content: 规则的具体内容这会被插入到发给AI的系统提示词中。实战技巧通过对话管理行为规则你不需要每次都去手动编辑文件。你可以直接告诉机器人“添加一条行为规则以后所有回复都要用中文。”“禁用ID为rule_005的规则。”“列出所有已启用的行为规则。”机器人会调用behavior_editor工具来执行这些操作。这是最“AI原生”的配置方式。但了解文件结构有助于你进行批量修改或从备份中恢复。我个人的经验我会创建一些基础规则比如定义回复的语言、语气专业/随意、是否包含emoji。然后针对特定场景创建临时规则例如在处理某个项目问题时添加一条“在讨论X项目时优先参考MEMORY.md中标签为‘project_x’的记忆”。用完后可以禁用或删除。这种动态的、上下文相关的规则管理让机器人显得非常灵活和智能。4.2 持久化记忆MEMORY.md构建机器人的“知识库”MEMORY.md是机器人的长期记忆存储同样使用JSONL格式。它用于存储那些需要跨对话会话记住的信息比如你的个人偏好、项目关键信息、重要的待办事项等。一个记忆条目示例{id: mem_20250321_001, timestamp: 2025-03-21T10:00:00Z, category: user_preference, importance: high, tags: [timezone, work_hours], content: The user prefers to use the CST (China Standard Time) timezone and typically works from 9 AM to 6 PM CST on weekdays.}importance: 可以设为low,medium,high。AI在组织回复时可能会更倾向于引用高重要性的记忆。tags: 标签数组用于对记忆进行分类和检索。如何有效利用记忆主动记忆当你告诉机器人一个重要信息时可以明确指示它记住。例如“记住我们项目的GitHub仓库地址是 https://github.com/xxx/yyy标签加上‘project_alpha’, ‘github’。”关联检索当你在后续对话中提及相关话题时AI会自动从记忆库中寻找带有相关标签或类别的记忆并融入到回复中使对话更具连续性。定期清理记忆库会不断增长。你可以定期让机器人总结旧的、低重要性的记忆或者手动删除过时的条目。可以添加一条定时任务来自动完成这个工作。注意记忆的“准确性”依赖于AI的理解。当你说“记住我住在北京”AI可能会将其转化为“用户位于北京”的记忆。但有时可能会产生歧义。对于极其关键的信息如API密钥、密码等绝对不要让机器人记忆。记忆库是明文存储的只应用于非敏感的上下文信息。4.3 定时任务SCHEDULE.md让机器人成为你的自动化助手这是Clawcord非常强大的一个功能。SCHEDULE.md文件允许你定义机器人自动执行的任务。格式同样是JSONL。示例定义一个每天上午9点CST检查某个网站状态的定时任务。{ id: daily_check, enabled: true, schedule: 0 9 * * *, timezone: Asia/Shanghai, channelId: 你的Discord频道ID, prompt: Check the status of our main API endpoint https://api.example.com/health. If its not returning status 200, alert me with the error message., lastRun: null, nextRun: 2025-03-22T01:00:00.000Z }schedule: 使用标准的cron表达式来定义执行频率。0 9 * * *表示每天9:00。timezone: 指定cron表达式所基于的时区。channelId: 任务执行后结果将发送到的Discord频道ID。prompt: 任务的核心。当任务触发时机器人会读取这个提示词然后像处理普通用户消息一样调用AI和工具比如http_fetch来执行它并将最终结果发送到指定频道。实战应用场景每日简报每天早上汇总特定RSS源、GitHub仓库动态或天气预报。定期监控每半小时检查服务器状态、网站证书有效期或数据库连接。提醒功能每周五下午5点提醒团队提交周报。数据聚合每天凌晨拉取前一天的业务数据让AI进行分析总结。配置技巧你可以让机器人帮你添加定时任务。例如“MyClawcord 添加一个定时任务每周一上午10点在频道#general里提醒大家开周会。” 机器人会引导你确认细节cron表达式、时区、频道然后调用schedule_editor工具将其写入文件。4.4 自定义命令与技能扩展agent-core/COMMANDS.md文件用于记录你为机器人定义的一些复杂工作流或常用指令。这更像是一个给“你自己”看的文档但机器人可以通过commands_registry工具来读取它当用户问“你能做什么”时它可以列出这些命令。例如你可以记录一个部署流程## 部署生产环境 1. SSH进入生产服务器 (ssh userprod) 2. 进入项目目录 (cd /opt/myapp) 3. 拉取最新代码 (git pull origin main) 4. 重启服务 (sudo systemctl restart myapp)这本身不是可执行代码但它规范了流程。你可以训练机器人“当我问‘部署到生产’时请参考COMMANDS.md中的‘部署生产环境’章节并逐步指导我操作。”更强大的扩展SkillsClawcord支持Claude Code SKILL.md格式的技能文件。你可以将技能文件放在~/.config/clawcord/skills/目录下。机器人启动时会加载这些技能并通过skills_reader工具在需要时调用。一个Skill文件通常包含技能描述、输入输出示例、以及相关的代码或逻辑说明。这相当于为机器人安装了一个个“插件”极大地扩展了其能力边界。例如你可以创建一个“图像描述生成器”技能当用户上传图片时机器人可以调用这个技能来生成描述文本。5. 高级配置、问题排查与安全实践5.1 模型选择策略与成本控制OpenRouter提供了从免费到顶尖付费的庞大模型库。如何选择日常闲聊与简单任务使用免费或隐匿模型如google/gemini-2.0-flash-exp:free、mistralai/mistral-7b-instruct:free。这些模型足以处理总结、简单问答、基于记忆的对话实现零成本运行。复杂推理与创意写作切换到中等性能付费模型如openai/gpt-4o-mini、anthropic/claude-3-haiku。它们性价比高适合代码审查、方案设计、内容润色等。高难度分析与精密任务启用顶级模型如openai/gpt-4o、anthropic/claude-3.5-sonnet。用于解决最复杂的问题但需注意成本。成本控制技巧设置预算提醒在OpenRouter仪表板设置每日或每月预算上限。环境变量切换你可以准备多个.env文件如.env.free,.env.paid通过脚本或手动切换OPENROUTER_MODEL变量根据任务需求灵活选择模型。监控使用量定期查看OpenRouter的Usage页面了解不同模型的消耗情况。5.2 启用与驯服危险的bash_exec工具bash_exec工具默认是关闭的ENABLE_BASH_TOOLfalse这是出于安全考虑。一旦启用AI将能够在你运行机器人的服务器上执行Shell命令。启用步骤在.env文件中设置ENABLE_BASH_TOOLtrue。重启机器人。安全防护机制Clawcord的bash_exec实现包含了一些基础防护命令黑名单会拦截明显的破坏性命令如rm -rf /、dd、mkfs等。执行超时命令执行有时间限制防止死循环。输出截断命令输出过长会被截断避免刷屏。即便如此风险依然极高AI可能会误解你的指令或在你未明确授权的情况下执行命令。我的强烈建议是仅在绝对必要时在受控的测试环境中启用。永远不要在生产服务器或存有重要数据的机器上启用此功能。考虑使用Docker容器来隔离运行环境限制其破坏范围。给AI设定明确的行为规则禁止其未经确认执行任何文件删除、系统修改等危险操作。5.3 常见问题与故障排除1. 机器人不响应消息或私信检查Message Content Intent这是最常见的原因。务必在Discord开发者门户的Bot设置中勾选此选项然后保存。重要修改此设置后你需要从服务器踢出机器人并使用新的邀请链接重新邀请。检查频道权限确保机器人在你它的频道拥有“读取消息”和“发送消息”的权限。检查.env配置确认DISCORD_TOKEN、DISCORD_CLIENT_ID、DISCORD_GUILD_ID填写正确没有多余的空格或换行。2. 机器人回复“I’m sorry, I cannot answer that question…”或类似内容检查OpenRouter API密钥和模型确认OPENROUTER_API_KEY有效且OPENROUTER_MODEL指定的模型名称正确无误区分大小写。可以先去OpenRouter的Playground测试一下API密钥和模型。检查账户余额/免费额度即使是免费模型也可能需要账户有足够的免费额度或已设置支付方式。查看机器人日志运行bun run dev的终端会输出详细日志包括AI API调用错误信息这是排查问题的第一手资料。3. 行为规则或记忆似乎没有生效检查文件格式确保BEHAVIOR.md和MEMORY.md是有效的JSONL格式。每一行必须是一个完整的JSON对象。一个常见的错误是忘记行尾的逗号或在文件末尾有多余的空行、逗号。可以使用在线的JSONL验证工具检查。重启机器人机器人只在启动时加载这些文件。修改文件后需要重启进程CtrlC后重新运行bun run dev。查看日志日志中会显示加载了多少条行为规则和记忆条目。4. 定时任务没有执行检查cron表达式和时区确保SCHEDULE.md中的schedule字段格式正确且timezone是有效的时区标识符如Asia/Shanghai。确认机器人进程在运行定时任务只在机器人主进程运行时才有效。如果进程崩溃或停止任务将无法触发。查看schedule-runner日志定时任务模块会定期打印日志显示下一次检查的时间以及触发了哪些任务。检查这些日志可以确认任务是否被正确调度。5.4 使用Docker进行容器化部署对于希望长期稳定运行或方便在不同环境迁移的用户使用Docker是个好选择。构建与运行# 1. 构建Docker镜像在项目根目录执行 docker build -t my-clawcord-bot . # 2. 运行容器 # 方式一通过环境变量文件推荐便于管理 # 首先将你的 .env 文件复制到安全位置或创建一个新的 docker run -d --name clawcord-bot \ --env-file /path/to/your/.env \ my-clawcord-bot # 方式二通过命令行传递环境变量不推荐不安全 docker run -d --name clawcord-bot \ -e DISCORD_TOKENyour_token \ -e DISCORD_CLIENT_IDyour_client_id \ -e DISCORD_GUILD_IDyour_guild_id \ -e OPENROUTER_API_KEYyour_key \ -e OPENROUTER_MODELyour_model \ my-clawcord-bot数据持久化默认情况下容器内的agent-core数据是临时的。为了持久化你的行为规则、记忆和任务你需要将宿主机的目录挂载到容器内。# 假设你在宿主机上有一个 /home/user/clawcord-data 目录 docker run -d --name clawcord-bot \ --env-file /path/to/your/.env \ -v /home/user/clawcord-data:/app/agent-core \ my-clawcord-bot这样容器内的/app/agent-core目录就会映射到宿主机的目录即使容器删除你的数据也不会丢失。镜像优化提示项目自带的Dockerfile已经比较精简。如果你需要进一步缩小镜像体积可以考虑使用多阶段构建或者使用基于Alpine Linux的Node.js镜像。不过对于这种个人使用的Bot官方镜像的便利性通常比那几十MB的体积差异更重要。