1. 项目概述ClaudeClaw一个为个人打造的持久化AI代理编排器如果你和我一样厌倦了每次与AI助手对话都要从头开始或者希望有一个能持续运行、记住上下文、并能通过不同渠道比如Slack、Telegram与你互动的智能伙伴那么ClaudeClaw可能就是你一直在找的那个工具。它不是一个庞大的企业级平台而是一个精巧、可深度定制的Claude Code插件核心目标只有一个让一个或多个Claude AI代理成为你数字生活的“常驻居民”。简单来说ClaudeClaw是一个持久化的代理编排器。它像一座永不关闭的指挥中心持续监听你设定的各种消息渠道目前支持Slack、WhatsApp、Telegram等将收到的消息路由给在独立、安全环境中运行的Claude代理并管理它们与你的长期对话记忆。这彻底改变了我们与AI的交互模式——从一次性的问答转变为持续的、有记忆的协作关系。想象一下你可以在家庭群聊里它询问晚餐食谱在工作Slack频道里让它分析代码提交或者通过一个简单的HTTP请求Webhook让它在CI/CD失败时自动介入调查。所有这些都是同一个“智能体”在不同场景下的分身且彼此记忆和权限完全隔离。这个项目的哲学非常吸引我“小到足以理解”。整个代码库大约3.5万token能完整放入Claude的上下文窗口。这意味着你或者Claude本身可以完全理解、审查甚至安全地修改它的每一行代码。没有复杂的微服务没有令人望而生畏的配置项。定制化不是通过填无数个YAML文件实现的而是直接修改代码——因为代码足够简单Claude可以帮你安全地完成修改。这种“AI原生”的设计理念让工具真正服务于个体用户而非试图满足所有人的通用需求。2. 核心架构与设计哲学拆解ClaudeClaw的架构清晰得令人愉悦它完美体现了“单一职责”和“隔离即安全”的设计思想。整个系统围绕一个核心的Node.js进程Orchestrator编排器展开我们可以将其拆解为几个关键部分来理解。2.1 消息流与核心循环系统的核心是一个永不停止的消息循环Message Loop。这个循环在src/orchestrator/message-loop.ts中实现它是整个系统跳动的心脏。其工作流程可以概括为以下几步监听与收集已注册的各个渠道Channel模块如Slack、WhatsApp持续监听外部事件。当有消息触发例如在Slack中被提及该渠道模块会将消息格式化后写入一个中心化的SQLite数据库store/messages.db。轮询与分派消息循环以固定频率例如每秒轮询数据库获取未被处理的新消息。对于每条消息它会根据其所属的“群组”Group进行路由。代理执行每个群组对应一个独立的、配置化的Claude代理。编排器会根据群组配置决定使用哪种运行时沙盒或容器来启动代理。它将当前对话上下文、系统提示词以及允许使用的工具列表传递给代理运行环境。响应与回写代理在隔离环境中运行调用必要的工具如Bash、读取文件、搜索记忆等进行思考并生成回复。回复内容通过进程间通信IPC传回编排器编排器再调用对应渠道的发送接口将回复送回到原始对话线程中。状态管理整个过程中的消息状态待处理、处理中、已完成、对话线程关系、以及每次运行的成本Token消耗、估算费用都会被记录在数据库中形成完整的可审计链路。这种基于数据库队列的异步设计保证了系统的可靠性和可扩展性。即使某个代理处理耗时较长也不会阻塞其他消息的处理。2.2 安全隔离沙盒与容器的抉择安全是ClaudeClaw设计的重中之重。它允许AI代理执行代码通过Bash工具和访问文件系统因此必须建立坚不可摧的隔离墙。项目提供了两种运行时隔离方案其选择体现了在安全、性能和便利性之间的权衡。沙盒运行时Sandbox默认且推荐这是项目的亮点。它并非使用沉重的Docker容器而是利用了Anthropic官方提供的anthropic-ai/sandbox-runtime包。这个包在操作系统内核层面实现进程沙盒化。在macOS上它使用苹果的Seatbelt沙盒框架。在Linux上它使用bubblewrap一个基于Linux命名空间的轻量级沙盒工具。 其原理是为每个代理进程生成一个详细的JSON配置文件明确声明网络权限通常只允许连接到api.anthropic.com和localhost。这意味着即使代理被恶意提示词诱导它也无法将你的API密钥或其他敏感数据外泄到任何其他网络地址。文件系统权限精确控制可读和可写的目录。例如为“家庭聊天”群组创建的代理其可读范围可能仅限于~/assistants/family/目录绝对无法触及~/assistants/work/下的任何工作文件。 这种方式的优势极其明显冷启动速度极快10ms没有容器带来的内存和磁盘开销并且由于是内核级强制隔离其安全边界比应用层的权限检查要可靠得多。代理进程以bypassPermissions模式运行意味着“沙盒本身就是信任边界”而非依赖代码逻辑去判断“这个操作是否被允许”。容器运行时Container作为备选方案支持使用DockerLinux或Apple ContainermacOS进行隔离。在这种模式下每个代理运行在一个独立的Linux容器中通过Volume挂载来访问指定的群组目录。为了安全真实的API密钥等凭证并不直接传递给容器而是通过一个运行在宿主机上的“凭证代理服务”进行注入。优势提供完全的网络隔离可自定义网络策略更符合传统的运维认知。劣势冷启动慢2-5秒资源开销大设置更复杂需要安装并运行Docker守护进程。我的实操心得对于绝大多数个人使用场景沙盒模式是毋庸置疑的首选。它的轻量、快速和“内核强制”的安全模型与ClaudeClaw“小而美”的哲学完全契合。只有在你有特殊需求比如需要在代理容器内运行自定义系统服务时才考虑容器模式。项目也支持按群组覆盖运行时你可以在某个群组的配置里单独指定runtime: container实现混合部署。2.3 结构化记忆系统让AI真正拥有“记忆”一个持久的代理核心价值在于其记忆能力。ClaudeClaw没有采用复杂的向量数据库而是设计了一套基于文件系统的、优雅的结构化记忆系统既简单又强大。每个群组目录下都有这样的结构groups/my-family/ ├── CLAUDE.md # 长期记忆文件每次会话都会加载 └── memory/ ├── 2024-05-15.md # 按日期生成的只追加日志 ├── 2024-05-16.md └── topics/ # 主题记忆 ├── vacation-plans.md └── home-maintenance.md代理可以通过三个核心工具与记忆交互memory_save: 将一条信息例如“女儿Alice的生日是7月10日”追加到当天的日志文件或写入指定的主题文件。memory_search: 使用grep在所有记忆文件日志、主题、CLAUDE.md中搜索关键词。未来可以通过/add-qmd技能升级为基于QMD的混合语义搜索。memory_get: 读取指定路径的记忆文件内容。记忆的持久化流程是智能化的在Claude的上下文窗口即将被压缩Compact前系统会触发一个PreCompact钩子自动将当前完整的对话记录存档到conversations/目录并将一个摘要写入当天的记忆日志。压缩完成后PostCompact钩子会验证记忆是否已成功保存。如果与API交互出错如达到速率限制StopFailure钩子会通过你的主频道通知你而不是让错误静默发生。这种设计的好处是记忆是人类可读的Markdown文件。你可以随时用文本编辑器打开memory/2024-05-16.md查看当天AI记住了什么也可以直接编辑CLAUDE.md来为AI注入固定的知识或指令。这种透明性和可控性是很多黑盒记忆系统所不具备的。3. 从零开始部署与深度配置指南让我们抛开理论动手搭建一个属于自己的ClaudeClaw实例。整个过程由Claude Code引导几乎不需要手动编写配置。3.1 环境准备与初始化首先确保你的系统满足基本要求macOS或LinuxNode.js 20以及已经安装好的Claude Code桌面应用。# 1. 克隆仓库 git clone https://github.com/sbusso/claudeclaw.git cd claudeclaw # 2. 启动Claude Code并加载当前目录为插件 # 这行命令会打开Claude Code并将当前claudeclaw目录识别为一个插件 claude # 此时Claude Code界面会打开。你需要切换到“终端”或对应的聊天界面。进入Claude Code后你只需要输入一条魔法指令/setup这个/setup命令是AI原生化体验的典范。Claude会启动一个交互式的配置向导带领你完成所有步骤安装依赖自动运行npm install安装项目所需的Node.js包。选择运行时询问你希望使用沙盒模式推荐还是容器模式。对于新手直接选择沙盒即可。配置消息渠道它会引导你为Slack、WhatsApp或Telegram等渠道配置认证。例如对于Slack它会要求你提供Bot Token和Signing Secret并指导你如何在Slack后台创建应用和获取这些凭证。这些凭证最终会保存在项目根目录的.env文件中。注册群组你会被问到想要创建哪些群组例如workfamily。每个群组会对应一个独立的文件夹和一套配置。启动服务最后Claude会帮你生成系统服务文件macOS上是launchd的plist文件Linux上是systemd service文件并启动后台服务。从此ClaudeClaw就会在后台默默运行监听你的消息。重要注意事项ClaudeClaw的实例状态.envstore/数据库groups/记忆都保存在当前工作目录。这意味着如果你想运行多个完全独立的ClaudeClaw实例例如一个用于个人一个用于公司项目你只需要创建不同的目录分别克隆或复制代码进去然后在各自的目录中运行claude和/setup即可。它们彼此之间是隔离的服务名也会基于目录名生成如com.claudeclaw.personal.plist。3.2 核心配置详解.env 与群组配置虽然/setup帮你生成了大部分配置但理解关键配置项对于后期调优至关重要。1. 环境变量 (.env).env文件保存了所有敏感信息和全局开关。主要条目包括# 运行时选择sandbox 或 container RUNTIMEsandbox # Anthropic API密钥必需 ANTHROPIC_API_KEYsk-ant-... # 各消息渠道的认证信息按需配置 SLACK_BOT_TOKENxoxb-... SLACK_SIGNING_SECRET... TELEGRAM_BOT_TOKEN... WHATSAPP_ACCESS_TOKEN... # Webhook触发所需的共享密钥 WEBHOOK_SECRETyour-super-secret-key-here # 主频道ID用于接收系统通知和管理命令 MAIN_CHANNEL_IDyour-personal-slack-channel-id安全警告务必确保.env文件被添加到.gitignore切勿提交到版本库。2. 群组配置 (groups/ /config.json)每个群组都可以有独立的代理行为配置。这是在群组目录下的一个JSON文件它让你能精细控制AI在该场景下的表现。{ agentConfig: { model: claude-3-5-sonnet-20241022, // 模型选择haiku(快/省), sonnet(平衡), opus(强/贵) effort: medium, // 推理努力程度影响思考深度和Token消耗 systemPrompt: 你是一个乐于助人的家庭助手负责管理家庭日程、食谱和购物清单。回答请简洁温馨。, // 追加到系统指令后 allowedTools: [Bash, Read, MemorySave, MemorySearch], // 允许使用的工具白名单 disallowedTools: [WebSearch], // 显式禁止的工具优先级高于allowedTools maxTurns: 20, // 单次对话最大回合数防止无限循环 costLimitUsd: 0.50 // 单次运行成本上限美元超限则中止 }, runtime: sandbox // 可选覆盖全局RUNTIME设置 }模型选择策略对于日常聊天、信息整理claude-3-haiku速度最快、成本最低对于复杂的代码分析或创作claude-3-opus能力最强claude-3-sonnet则是平衡之选。你可以根据群组用途差异化配置。工具控制这是安全的关键。在家庭群组你可能只开放Read和记忆工具在工作开发群组则需要开放Bash来运行构建脚本。务必遵循最小权限原则。成本限制设置costLimitUsd是一个好习惯它能防止意外复杂的任务导致巨额API费用。当一次运行估算成本超过此限值代理会收到“预算不足”的通知并停止。3.3 扩展系统按需安装功能模块ClaudeClaw的核心非常精简额外功能通过“扩展Extension”系统安装。这避免了核心代码的膨胀让你可以只安装需要的功能。安装扩展通常通过Claude Code中的技能命令完成。例如要安装Slack渠道支持如果初始setup没配置/install-extension slack这个命令会从官方仓库拉取claudeclaw-slack扩展代码并引导你完成配置。安装后扩展会向核心系统注册自己包括IPC处理器用于响应特定类型的内部事件。数据库Schema扩展所需的数据库表。启动钩子在服务启动时执行初始化逻辑。环境变量提示用户需要配置哪些新的.env变量。目前官方维护的扩展包括claudeclaw-slack: Slack渠道集成。claudeclaw-triage: 一个非常实用的“分诊”代理扩展。它可以作为一线支持分析用户反馈用自然语言回复用户并在需要代码变更时自动创建GitHub Issue同时将技术任务排入开发队列。这种设计意味着社区可以轻松贡献新的渠道如Discord、Gmail或功能扩展如与Obsidian笔记同步而无需修改核心代码。4. 高级用法与实战场景解析当基础服务跑起来后ClaudeClaw的真正威力在于如何将它融入你的工作流。以下是我在实际使用中总结的几个核心场景和技巧。4.1 触发代理的三种方式ClaudeClaw的代理可以通过多种方式唤醒适应不同场景渠道消息触发最常用在已集成的Slack、Telegram等渠道中直接你的机器人默认是ClaudeClaw并发送指令。例如在家庭Slack频道里ClaudeClaw 根据冰箱里的鸡蛋、西红柿和面条推荐三个简单的晚餐方案。代理会结合之前的饮食偏好记忆来回答。计划任务触发自动化你可以让代理在特定时间自动运行。这是通过类似cron的表达式或间隔时间来配置的。例如你可以设置ClaudeClaw 每个工作日上午9点发送销售管道概览到#sales频道。ClaudeClaw 每周五下午6点审查本周的git提交历史如果README有滞后就更新它。这些任务定义会被保存并由后台调度器准时执行。任务产生的输出可以发送回指定的频道。Webhook触发系统集成这是将ClaudeClaw接入其他系统的强大方式。任何能发送HTTP POST请求的服务都可以触发代理。你需要先在.env中设置WEBHOOK_SECRET。# 示例当CI/CD流水线失败时触发代理分析日志 PAYLOAD{prompt: CI构建在main分支失败错误日志见附件。请分析根本原因并给出修复建议摘要。} # 生成HMAC-SHA256签名 SIGNATURE$(echo -n $PAYLOAD | openssl dgst -sha256 -hmac $WEBHOOK_SECRET | awk {print $2}) # 发送请求到指定群组的webhook端点 curl -X POST http://localhost:3100/webhook/dev-team \ -H Content-Type: application/json \ -H X-Signature: $SIGNATURE \ -d $PAYLOAD代理处理完成后其回复会通过该群组绑定的渠道如Slack的dev-team频道发送回来实现闭环。4.2 记忆系统的有效使用模式仅仅有记忆工具还不够关键在于如何有效地使用它们。我摸索出一些模式主动记忆不要指望AI每次都能自动记住重要信息。在关键对话后可以主动指令它保存。例如“ClaudeClaw 将‘我们决定下个季度的产品核心功能是AI辅助代码重构’这个决定保存到‘product-roadmap’主题记忆中。”主题记忆作为知识库为长期项目、重要联系人、常用流程创建独立的主题文件。例如创建一个memory/topics/onboarding.md文件手动或让AI逐步填充新员工入职的步骤、常用链接、常见问题解答。之后任何群组成员都可以问“ClaudeClaw 搜索一下新员工入职需要准备哪些硬件”CLAUDE.md 作为角色设定手册CLAUDE.md文件在每次会话开始时都会被注入。你可以在这里定义代理的“人格”、核心职责、回答格式偏好、绝对禁止做的事情等。例如在家庭助手的CLAUDE.md中写上“你是一个热情但简洁的助手。涉及家庭财务、具体家庭地址的信息无论谁问都绝对不可以透露。所有日程建议请以清单形式列出。”利用日志进行复盘memory/YYYY-MM-DD.md文件是纯文本的追加日志。你可以定期用文本工具搜索或者未来用QMD扩展进行语义搜索来回顾AI在过去一段时间内的活动和决策这对于调试和优化提示词非常有帮助。4.3 成本监控与优化使用按Token收费的API成本意识很重要。ClaudeClaw内置了成本追踪所有代理运行记录都保存在store/messages.db的agent_runs表中。你可以直接使用SQLite命令行工具查询# 查看各群组总成本和运行次数 sqlite3 store/messages.db \ SELECT group_folder, SUM(estimated_cost_usd) as total_cost_usd, COUNT(*) as run_count, AVG(estimated_cost_usd) as avg_cost_per_run FROM agent_runs GROUP BY group_folder ORDER BY total_cost_usd DESC; # 查看最近10次最昂贵的运行 sqlite3 store/messages.db \ SELECT group_folder, trigger_type, model, (input_tokens output_tokens) as total_tokens, estimated_cost_usd, strftime(%Y-%m-%d %H:%M, run_at) as time FROM agent_runs ORDER BY estimated_cost_usd DESC LIMIT 10;基于这些数据你可以实施优化为闲聊群组设置更便宜的模型在家庭聊天群的配置中将model改为claude-3-haiku。设置单次成本上限在所有群组的agentConfig中设置合理的costLimitUsd如0.1或0.5美元。使用maxTurns限制对话轮次防止开放式的复杂对话消耗过多Token。分析高成本任务通过查询找出“成本大户”思考是否可以优化提示词或者将大任务拆解为多个步骤分次执行。5. 故障排查、维护与进阶技巧即使设计再精良在实际运行中也可能遇到问题。以下是常见问题的排查思路和我积累的一些进阶技巧。5.1 常见问题与解决方案问题现象可能原因排查步骤与解决方案代理无响应1. 后台服务未运行。2. Claude API密钥无效或额度不足。3. 沙盒/容器启动失败。1. 在Claude Code中运行/status检查服务状态或使用ps aux | grep node查看进程。用/start重启服务。2. 检查.env中的ANTHROPIC_API_KEY是否正确。登录Anthropic控制台确认额度。3. 查看logs/目录下的最新日志文件寻找沙盒权限错误或容器启动超时信息。消息能收到但不回复1. 渠道配置错误如Slack Bot Token权限不足。2. 对应群组的代理配置有误如maxTurns为0。3. 数据库队列堵塞。1. 检查渠道配置确保Bot有发送消息的权限并且已加入到目标频道。2. 检查groups/group-name/config.json文件格式和内容是否正确。3. 尝试在Claude Code中手动触发一次该群组的代理看是否有错误输出。记忆工具调用失败1. 沙盒的文件系统权限设置过严。2. 记忆文件路径不存在或权限错误。1. 检查沙盒运行时生成的配置文件通常在临时目录确认allowRead和allowWrite包含了群组目录。2. 确保groups/group-name/memory/目录存在且可写。可以手动创建。Webhook触发返回4031.WEBHOOK_SECRET未设置或不匹配。2. 签名头X-Signature计算错误。1. 确认发送请求的服务器和ClaudeClaw服务使用的WEBHOOK_SECRET完全一致。2. 使用提供的openssl命令精确计算签名确保payload字符串没有多余空格或换行。可以在服务端日志中查看预期的签名。计划任务不执行1. 系统的定时任务服务cron或systemd timer未正确安装或激活。2. 任务定义格式错误。1. 运行/debug schedule查看任务列表和状态。检查macOS的launchd plist文件或Linux的systemd timer是否已加载并启用。2. 在Claude Code中重新创建一次计划任务。日志是排查问题的第一线索。ClaudeClaw的日志默认输出到logs/目录按日期分割。关注error级别的日志它们通常能直接指出问题所在。5.2 日常维护与升级更新代码由于你的实例是一个独立的目录升级时可以直接进入该目录拉取上游仓库的最新更改。cd ~/assistants/personal-claudeclaw git pull origin main # 如果package.json有变化需要重新安装依赖 npm install # 然后通过Claude Code的 /restart 技能重启服务注意.envstore/groups/都在.gitignore中所以拉取代码不会覆盖你的配置和记忆。备份最重要的资产是你的记忆和配置。定期备份整个实例目录或者至少groups/和.env文件是明智之举。你可以写一个简单的脚本用rsync或tar打包目录到云存储。监控除了成本SQL查询你可以让ClaudeClaw自己报告健康状态。设置一个计划任务让代理每天检查自己的日志并摘要发送到主频道报告过去24小时的消息量、错误次数和总成本。5.3 进阶定制修改代码与贡献技能ClaudeClaw鼓励你“拥有”自己的代码。当内置功能不满足需求时你可以直接修改源代码。例如你想改变默认的触发词ClaudeClaw为Bob在Claude Code中打开项目文件找到定义触发词的地方通常在渠道注册或消息解析的逻辑中。直接告诉Claude“请帮我把所有渠道的触发词从‘ClaudeClaw’改为‘Bob’。”Claude会分析代码给出具体的修改建议和代码差异。你确认后它会执行修改。修改完成后运行/restart使更改生效。这种“通过对话编程”的方式极大地降低了定制门槛。项目也欢迎以“技能Skill”的形式贡献代码。一个技能是一个完整的、可分享的功能模块包如/add-telegram。如果你开发了一个有用的功能可以按照扩展系统的规范打包它并提交到社区。5.4 安全最佳实践密钥管理ANTHROPIC_API_KEY和各类渠道的Bot Token是最高机密。除了保存在.env文件考虑使用系统的密钥链如macOS的Keychain或加密工具进行二次保护。切勿在代码或日志中硬编码。沙盒权限审查虽然沙盒配置是自动生成的但你应该理解其原理。定期检查沙盒设置文件确保网络白名单allowedDomains没有包含可疑域名文件系统路径限制严格。工具最小化严格遵守最小权限原则。对于不需要执行代码的群组在agentConfig中从allowedTools列表移除Bash工具。对于不需要网络搜索的群组移除WebSearch。系统隔离如果条件允许将ClaudeClaw运行在一个专用的用户账户或轻量级虚拟机中进一步隔离潜在风险。审计日志利用内置的agent_runs数据库表定期审计代理的活动特别是关注那些成本异常或触发频繁的运行以识别潜在的滥用或提示词注入攻击。ClaudeClaw代表了一种新的AI工具范式它轻量、透明、可审计并且将控制权完全交还给用户。它不是一个黑盒服务而是一个你可以理解、调整并与之共同成长的数字伙伴。从简单的自动化提醒到复杂的多代理协作工作流它的边界只取决于你的想象力和你愿意赋予它的权限。开始于一个简单的/setup它或许能逐渐成长为你的个人数字世界中最得力的那个“常驻大脑”。