1. 项目概述为AI助手装上“安全锁”如果你和我一样日常工作重度依赖像Cursor、Claude Code这类AI编程助手那你肯定体验过那种又爱又怕的感觉。爱的是它们能极大提升效率一个指令就能生成代码、重构文件怕的是你永远不知道它下一个操作会不会“手滑”把某个重要目录给删了或者未经你同意就把本地数据上传到某个未知的服务器。这种对AI代理Agent行为的不透明和不可控就像把车钥匙交给一个驾驶技术高超但路怒症发作机制不明的司机你永远悬着一颗心。这就是我最初寻找和最终选择使用claw-diary的核心原因。它本质上是一个AI代理行为审计与安全审批系统。你可以把它想象成安装在你的AI助手和操作系统之间的一个“透明防火墙”和“黑匣子记录仪”。它默默地记录下AI助手在你电脑上执行的所有操作一旦检测到高风险行为——比如删除文件、修改系统配置、进行网络传输——它会立刻通过Telegram向你发送通知请求你的手动批准。只有你明确说“行”这个操作才会真正执行你说“不行”它就会被拦截。这个工具完美地实现了“人类在环”Human-in-the-Loop的安全理念把最终控制权牢牢握在你自己手里。对于开发者、数据分析师或者任何使用AI代理处理敏感任务的用户来说它提供的不仅仅是安全更是一种宝贵的“可观测性”。你可以通过它清晰的每日摘要和时间线视图复盘AI助手一天都干了什么理解它的行为模式这对于调试复杂的AI工作流和建立信任至关重要。2. 核心架构与工作原理拆解claw-diary之所以能实现既轻量又强大的监控能力其技术选型功不可没。它不是在你的本地跑一个笨重的桌面监控程序而是采用了一种更现代、更高效的“本地代理 云端控制中心”的混合架构。2.1 前端与本地代理轻量级的数据采集器运行在你电脑上的部分实际上是一个轻量级的本地代理程序。它的职责非常专注钩子Hook与拦截它通过系统级的钩子或与AI开发工具如Cursor、通过MCP协议深度集成能够监听AI代理发出的文件操作、Shell命令、网络请求等指令。行为序列化将监听到的操作转化为结构化的日志事件包含时间戳、发起代理的名称、操作类型读、写、删、执行、目标路径/命令、风险等级等关键元数据。安全策略匹配根据内置或用户自定义的安全策略初步判断该操作是否属于“高风险”范畴。例如任何包含rm -rf、del /s的命令或是对系统目录、用户文档根目录的写操作都会被自动标记为高风险。通信将事件日志和待审批的高风险操作通过安全的HTTPS连接发送到云端控制中心。这个本地代理设计得非常精简几乎不占用系统资源因为它不负责复杂的逻辑判断和存储只做最核心的采集和转发。2.2 云端控制中心基于Cloudflare边缘计算的大脑所有复杂的逻辑都运行在云端具体来说是构建在Cloudflare Workers无服务器平台上。这是整个系统的“大脑”其优势非常明显无需运维你完全不用关心服务器配置、扩容、安全补丁Cloudflare全包了。全球低延迟Workers在全球数百个边缘节点运行无论你在哪里请求都能被快速处理这对于需要实时审批的体验至关重要。成本极低对于个人或小团队的使用量Workers的免费额度完全够用几乎零成本运行。这个“大脑”的核心组件包括Hono框架这是一个为边缘环境优化的轻量级Web框架用于快速构建处理HTTP请求的API端点比如接收本地代理的日志、处理Telegram bot的回调。D1数据库Cloudflare提供的基于SQLite的边缘数据库。它用于持久化存储所有的审计日志、用户配置、待审批的任务队列。D1的优势在于它能与Workers无缝集成在同一个边缘节点处理数据和逻辑避免了传统架构中应用服务器与数据库之间的网络延迟。Durable Objects这是实现“实时审批”状态同步的关键。当你的本地代理上报一个高风险操作时云端会创建一个Durable Object来代表这个特定的审批会话。这个对象保存着审批状态待定、已批准、已拒绝并且能同时与等待结果的本地代理、以及向你发送通知的Telegram Bot保持WebSocket或长轮询连接。当你通过Telegram回复后该对象会立即将状态更新推送给所有相关方确保操作能被即时执行或终止。2.3 审批流与通知Telegram Bot作为控制终端Telegram Bot是整个系统与你交互的神经末梢也是“人类在环”理念的最终体现点。事件触发云端控制中心收到高风险事件后会根据你注册的Telegram用户ID通过Telegram Bot API发送一条结构化的消息。这条消息会清晰地告诉你哪个AI代理例如“Cursor Agent”、在什么时间、试图执行什么操作例如“删除路径/projects/important_backup”。交互式审批消息会附带内联键盘按钮通常是“✅ 批准”和“❌ 拒绝”。你只需点击即可无需输入复杂命令。系统也支持文本命令如/approve [task-id]以满足更多场景。状态同步你的点击动作会触发一个回调到云端Workers。Workers找到对应的Durable Object更新状态并立即通知在等待的本地代理执行或放弃操作。同时Bot会给你发送一条操作结果确认消息形成闭环。这套架构的精妙之处在于它将计算密集和状态管理部分卸载到了强大且免运维的边缘云本地只保留最轻量的传感器而将最方便的人机交互界面放在了你几乎时刻在线的即时通讯工具里。这实现了安全、实时、便捷的完美平衡。3. 从零开始部署与配置实战理解了原理我们来看看如何亲手把它搭建起来。整个过程可以分为云端部署和本地配置两大部分。3.1 云端服务部署基于Cloudflare这是最核心的一步因为你需要有自己的控制中心。别担心即使你不是DevOps专家按照步骤也能完成。第一步准备工作注册一个 Cloudflare 账户。如果你已经有账户直接登录。准备一个域名可以是免费的子域名比如xxx.pages.dev并将其DNS托管到Cloudflare。这一步是使用Workers和D1所必需的。在Telegram中搜索BotFather创建一个新的Bot并获取其API Token。记下这个Token这是你的Bot和云端通信的密码。第二步克隆并配置项目打开终端执行以下命令git clone https://github.com/cyberindranil/claw-diary.git cd claw-diary项目根目录下应该有一个wrangler.toml示例文件或.dev.vars示例文件。你需要创建或修改它填入你的配置# wrangler.toml name my-claw-diary compatibility_date 2024-08-01 [[d1_databases]] binding DB # 在Worker代码中使用的变量名 database_name claw-diary-db database_id # 稍后创建D1数据库后会获得先留空 # 定义用于Telegram Bot回调的KV命名空间如果需要存储会话 kv_namespaces [ { binding SESSION_STORE, id } # 同样稍后创建 ] # 环境变量敏感信息不要直接写在这里用.dev.vars [vars] TELEGRAM_BOT_TOKEN # 从BotFather获取 ALLOWED_TELEGRAM_USERNAME your_telegram_username # 你的Telegram用户名不带更安全的做法是创建.dev.vars文件来存储敏感信息该文件已被.gitignoreTELEGRAM_BOT_TOKEN你的Bot Token第三步创建Cloudflare资源创建D1数据库npx wrangler d1 create claw-diary-db执行成功后命令行会输出database_id和database_name。将database_id填回wrangler.toml文件中的对应位置。初始化数据库表结构查看项目schema.sql文件使用Wrangler执行它来创建表。npx wrangler d1 execute claw-diary-db --file./schema.sql创建KV命名空间可选用于增强会话管理npx wrangler kv:namespace create SESSION_STORE获取返回的id并填入wrangler.toml。第四步部署Worker在项目根目录下运行npm run deploy # 或者直接使用 wrangler npx wrangler deploy部署成功后你会获得一个你的Worker域名例如my-claw-diary.your-account.workers.dev。记下这个地址它是你本地代理需要连接的云端地址。第五步配置Telegram Webhook为了让Telegram能将你的点击事件推送到你的Worker需要设置Webhook。假设你的Worker地址是https://my-claw-diary.your-account.workers.dev那么Webhook地址就是https://my-claw-diary.your-account.workers.dev/telegram-webhook。 你可以通过一个简单的cURL命令来设置curl -F urlhttps://my-claw-diary.your-account.workers.dev/telegram-webhook \ https://api.telegram.org/bot你的TELEGRAM_BOT_TOKEN/setWebhook看到{ok:true,result:true,description:Webhook was set}这样的返回就说明成功了。实操心得环境变量与安全永远不要将TELEGRAM_BOT_TOKEN等敏感信息提交到Git仓库。wrangler.toml中的[vars]部分在部署时会被打包对于生产环境更推荐使用Cloudflare Dashboard中Workers设置的“环境变量”界面进行配置这样更安全。本地开发时使用.dev.vars文件。3.2 本地代理安装与连接云端就绪后接下来是在你的工作电脑上安装本地代理。第一步下载与安装根据你的操作系统从项目的Release页面下载最新的本地代理安装包。对于Windows用户通常是一个.exe安装程序macOS可能是.dmg或通过Homebrew安装Linux则可能是.deb、.rpm或AppImage。 运行安装程序按照指引完成安装。安装过程通常会在系统托盘创建一个常驻图标。第二步首次运行与配置启动claw-diary本地代理。首次运行会弹出一个配置向导窗口。关键配置项Cloudflare Worker URL填入你上一步部署获得的地址例如https://my-claw-diary.your-account.workers.dev。Telegram Username输入你的Telegram用户名不带这用于云端验证审批请求的来源是否合法。Agent Integration选择你要监控的AI代理。通常支持Cursor如果安装了Cursor代理会自动检测并注入钩子。MCPModel Context Protocol Server对于支持MCP协议的AI工具如某些Claude桌面端你需要配置MCP服务器的连接地址和密钥。通用系统监控一个更底层的模式尝试监控所有进程的特定系统调用如文件删除、网络连接但可能误报率较高需要精细调整规则。保存配置并重启代理。此时本地代理会尝试与你的云端Worker建立连接并向你的Telegram Bot发送一条测试消息如“claw-diary已成功连接”。收到这条消息证明整个链路已经打通。第三步验证与测试打开你配置的AI代理如Cursor尝试执行一个明确的高风险操作例如在终端里输入一个删除测试文件的命令或者让AI助手执行一个包含fs.unlinkNode.js删除文件的代码。立即检查你的Telegram。你应该在几秒内收到一条审批请求。点击“批准”或“拒绝”观察AI代理的命令是否被相应执行或阻断。同时打开claw-diary的本地UI通常可以通过系统托盘图标打开或访问http://localhost:3000在“时间线”里应该能看到刚刚记录的这条事件及其审批状态。注意事项防火墙与网络确保你的电脑防火墙没有阻止本地代理的出站连接到你的Cloudflare Worker域名。如果你的网络环境有代理可能需要在本地代理的设置中配置HTTP代理。连接失败最常见的原因就是网络问题。4. 核心功能深度使用与策略调优系统跑起来只是第一步让它真正贴合你的工作流发挥最大价值还需要深入理解和配置其核心功能。4.1 审计日志与时间线你的AI行为“仪表盘”claw-diary的Web界面是你进行事后审计和分析的主战场。它主要提供两个视图每日摘要以天为单位汇总展示高风险操作的数量、被批准/拒绝的比例、最活跃的AI代理等统计信息。适合每天花几分钟快速浏览掌握整体情况。时间线这是一个按时间倒序排列的详细事件流。每一条记录都包含时间戳代理名称如“Cursor-Agent-1”操作类型图标文件、命令、网络等操作描述如“Attempt to delete file: ~/documents/draft.txt”风险等级高、中、低审批状态待定、已批准、已拒绝、已忽略高级使用技巧过滤与搜索充分利用时间线顶部的过滤栏。你可以按代理名称、操作类型文件操作、命令执行、网络访问、风险等级、日期范围进行筛选。这对于从海量日志中定位特定问题至关重要。导出日志对于需要长期存档或进一步分析如用ELK Stack的场景定期通过界面导出JSON格式的日志文件。定义“噪音”与忽略规则你会发现某些低风险或重复的操作如AI助手频繁读取某个配置文件会产生大量日志干扰视线。你可以在设置中为特定代理或特定文件路径模式创建“忽略规则”让这些操作不再记录或无需审批。4.2 安全策略引擎从“一刀切”到“精细化管控”初始安装后claw-diary使用一套默认的安全策略。但真正的威力在于自定义策略。你可以通过编辑本地代理的配置文件通常是config.yaml或config.json来定义规则。一个策略规则通常包含以下几个部分rules: - name: Protect Documents Folder description: 任何对‘我的文档’目录的写/删操作都需要审批 target: agent # 规则应用于所有代理或指定某个代理 conditions: - type: file_system operation: [write, delete] # 监控写和删除操作 path_pattern: /home/username/Documents/** # 路径匹配模式**表示递归所有子目录 risk_level: high action: require_approval # 触发时需要审批 - name: Block Internet Access to Unknown Domains description: 阻止AI代理访问非白名单域名 target: agent conditions: - type: network protocol: tcp hostname_pattern: * # 匹配所有域名 whitelist: [api.openai.com, *.github.com] # 白名单允许访问OpenAI和GitHub risk_level: high action: block # 直接阻止无需审批 - name: Log Low Risk Reads description: 仅记录对项目源代码目录的读取操作 target: cursor-agent conditions: - type: file_system operation: [read] path_pattern: /projects/**/*.js # 只监控.js文件的读取 risk_level: low action: log_only # 仅记录不拦截也不需审批策略调优思路从宽到严初期可以先设置较宽松的策略主要拦截明确的删除命令和敏感路径的写入。运行一段时间后分析时间线日志看看AI代理通常访问哪些路径、执行哪些命令再逐步收紧策略。基于角色/代理的差异化策略你可以为“代码生成助手”和“数据分析助手”设置不同的策略。前者可能更关注对src/目录的写入后者则需严防对数据库凭证文件的读取。利用路径模式熟练使用*(匹配任意字符) 和**(递归匹配) 通配符来定义范围避免为每个具体文件写规则。4.3 审批流程与自动化进阶基础的点击审批已经很强大了但claw-diary还支持更高级的自动化审批以平衡安全与效率。基于规则的自动审批对于你完全信任的、模式固定的低风险操作可以设置规则自动批准。例如允许某个代理在/tmp/目录下任意创建和删除临时文件。rules: - name: Auto-approve Temp File Operations conditions: - type: file_system path_pattern: /tmp/** risk_level: low action: auto_approve # 满足条件则自动批准审批超时处理你可以设置审批请求的超时时间如5分钟。如果超时未处理系统可以执行默认操作default_action比如“拒绝”以保安全或者对于特定规则设为“批准”以避免工作流阻塞。批量审批Telegram Bot支持发送包含多个待审批任务的摘要消息你可以通过一条命令批量批准或拒绝同一类别下的所有操作。实操心得信任的建立是渐进的不要一开始就追求全自动。建议在至少一两周的人工审批观察期后再开始设置自动批准规则。你会更清楚地知道哪些操作是常规的、安全的。同时即使设置了自动批准也定期复查“时间线”里这些被自动批准的操作确保没有异常。5. 集成与扩展融入你的开发生态claw-diary不是一个孤岛它可以很好地与现有工具链集成。5.1 与Cursor深度集成对于Cursor用户集成是最无缝的。安装claw-diary本地代理后它通常会通过Cursor的插件系统或MCP服务器集成自动注入。效果在Cursor中当AI建议运行一个终端命令或修改文件时如果该操作触发了claw-diary的高风险规则你会直接在Cursor的UI中看到一个悬浮通知或状态栏提示告知你操作正在等待审批同时Telegram通知也会发出。配置确保在claw-diary配置中启用了“Cursor Integration”选项并且Cursor的MCP设置中指向了正确的本地claw-diary MCP服务器地址通常是http://localhost:3001。5.2 通过MCP协议支持其他AI工具MCPModel Context Protocol正在成为AI工具与外部服务通信的标准协议。claw-diary实现了MCP Server这意味着任何支持MCP客户端的AI工具如未来可能支持的Claude桌面端、其他代码助手都可以连接到它。如何工作claw-diary的MCP Server暴露了一系列“工具”tools例如get_audit_logs、request_approval。AI工具可以通过MCP调用这些工具来查询日志或声明自己将要执行的操作从而触发审批流程。手动连接在你的AI工具配置中找到MCP服务器设置添加一个新的服务器地址为http://localhost:3001claw-diary本地代理默认的MCP端口并可能需要提供在claw-diary中生成的认证令牌。5.3 自定义告警与通知渠道虽然Telegram是官方推荐且体验最好的渠道但如果你有更复杂的通知需求可以通过扩展Cloudflare Worker来实现。添加其他Bot你可以修改Worker代码在发送Telegram通知的同时向Slack、Discord或企业微信的Webhook地址发送一条消息。分级告警可以修改逻辑对不同风险等级的事件采用不同的通知方式。例如高风险操作同时发Telegram和短信通过Twilio等API中风险只发Telegram低风险仅记录不通知。与监控系统集成将审计日志导出到如Prometheus Grafana或Datadog中可以绘制AI代理活动趋势图、风险操作统计等仪表盘实现更专业的运维监控。6. 故障排查与性能优化实录即使设计再完善在实际部署和长期使用中也会遇到问题。以下是我和社区用户遇到的一些典型情况及解决方法。6.1 常见问题速查表问题现象可能原因排查步骤与解决方案收不到Telegram审批消息1. Bot Token或用户名配置错误。2. Webhook未正确设置或失效。3. 网络问题导致Worker无法访问Telegram API。1. 检查Worker环境变量TELEGRAM_BOT_TOKEN和ALLOWED_TELEGRAM_USERNAME是否正确。2. 访问https://api.telegram.org/botYOUR_TOKEN/getWebhookInfo查看Webhook状态和最后错误信息。3. 在Cloudflare Worker日志中查看发送消息时的错误响应。本地代理无法连接云端Worker1. Worker部署失败或域名错误。2. 本地网络代理/防火墙阻止。3. Worker代码存在运行时错误。1. 在浏览器中直接访问你的Worker URL应返回健康状态如{status:ok}。2. 在本地代理日志通常位于~/.claw-diary/logs/中查找连接错误。3. 检查Cloudflare Dashboard中Worker的“日志”面板看是否有未处理的异常。高风险操作未被拦截1. 本地代理与AI工具集成未生效。2. 安全策略规则未覆盖此操作。3. 操作未被识别为高风险。1. 确认AI工具如Cursor已重启且claw-diary集成已启用。2. 检查时间线看该操作是否被记录即使未拦截。如果没记录是集成问题如果记录了但风险等级低是规则问题。3. 调整或新增安全策略规则确保目标路径和操作类型被正确匹配。时间线界面加载缓慢1. D1数据库日志表数据量过大。2. Worker查询未优化或缺少索引。3. 网络延迟。1. 在Worker中实现日志自动归档或清理策略如只保留30天数据。2. 检查schema.sql为经常查询的字段如timestamp,agent_name,risk_level创建索引。3. 考虑对时间线实现分页查询而非一次性加载全部。Durable Objects状态不同步1. Durable Object创建失败。2. 本地代理与Worker之间的WebSocket连接中断。1. 查看Worker日志中关于Durable Object实例化的错误。2. 确保本地代理的网络稳定并检查其重连逻辑。可以尝试重启本地代理。6.2 性能优化与维护建议数据库优化定期清理在Worker中设置一个定时触发器Cron Trigger每天凌晨执行一次删除超过一定天数如90天的旧日志。对于审批任务表完成后即可删除或移至历史表。添加索引务必为D1数据库的审计表添加索引。最基本的索引应该建立在timestamp用于按时间排序和范围查询和(agent_name, risk_level)用于过滤上。CREATE INDEX IF NOT EXISTS idx_audit_logs_timestamp ON audit_logs(timestamp); CREATE INDEX IF NOT EXISTS idx_audit_logs_agent_risk ON audit_logs(agent_name, risk_level);Worker逻辑优化异步处理对于非实时关键路径如发送非紧急通知、写入次要日志使用waitUntil()API使其在响应返回后异步执行不阻塞主请求。缓存静态配置将安全策略规则等不常变化的数据缓存在Worker的全局变量或KV中避免每次请求都从D1读取。本地代理资源占用正常情况下本地代理内存占用应小于50MB。如果发现异常增高检查是否开启了“通用系统监控”模式该模式可能产生大量事件。调整为更精确的、基于特定工具如Cursor的集成模式。安全加固Telegram Token保密如前所述使用环境变量或Cloudflare Secrets管理Token。限制Worker访问可以在Worker的触发器中设置路由限制或通过简单的Token认证确保只有你的本地代理可以调用核心API。定期更新关注项目GitHub的Release及时更新本地代理和Worker代码以获取安全补丁和新功能。经过一段时间的深度使用claw-diary已经从最初的一个安全工具变成了我理解和优化AI工作流不可或缺的“观察窗”。它带来的安心感让我能更放手地让AI代理去处理复杂任务而我知道有一双可靠的眼睛和一道坚实的保险杠在守护着。如果你也在探索AI辅助编程或自动化强烈建议你花点时间部署它这份对控制感的投资绝对物超所值。