claw-diary：为AI编程助手构建行为审计与安全审批系统

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 前端与本地代理：轻量级的数据采集器

运行在你电脑上的部分，实际上是一个轻量级的本地代理程序。它的职责非常专注：

1. 钩子（Hook）与拦截：它通过系统级的钩子或与AI开发工具（如Cursor、通过MCP协议）深度集成，能够监听AI代理发出的文件操作、Shell命令、网络请求等指令。
2. 行为序列化：将监听到的操作转化为结构化的日志事件，包含时间戳、发起代理的名称、操作类型（读、写、删、执行）、目标路径/命令、风险等级等关键元数据。
3. 安全策略匹配：根据内置或用户自定义的安全策略，初步判断该操作是否属于“高风险”范畴。例如，任何包含rm -rf、del /s的命令，或是对系统目录、用户文档根目录的写操作，都会被自动标记为高风险。
4. 通信：将事件日志和待审批的高风险操作，通过安全的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是整个系统与你交互的神经末梢，也是“人类在环”理念的最终体现点。

1. 事件触发：云端控制中心收到高风险事件后，会根据你注册的Telegram用户ID，通过Telegram Bot API发送一条结构化的消息。这条消息会清晰地告诉你：哪个AI代理（例如“Cursor Agent”）、在什么时间、试图执行什么操作（例如“删除路径：/projects/important_backup”）。
2. 交互式审批：消息会附带内联键盘按钮，通常是“✅ 批准”和“❌ 拒绝”。你只需点击即可，无需输入复杂命令。系统也支持文本命令（如/approve [task-id]）以满足更多场景。
3. 状态同步：你的点击动作会触发一个回调到云端Workers。Workers找到对应的Durable Object，更新状态，并立即通知在等待的本地代理执行或放弃操作。同时，Bot会给你发送一条操作结果确认消息，形成闭环。

这套架构的精妙之处在于，它将计算密集和状态管理部分卸载到了强大且免运维的边缘云，本地只保留最轻量的传感器，而将最方便的人机交互界面放在了你几乎时刻在线的即时通讯工具里。这实现了安全、实时、便捷的完美平衡。

3. 从零开始部署与配置实战

理解了原理，我们来看看如何亲手把它搭建起来。整个过程可以分为云端部署和本地配置两大部分。

3.1 云端服务部署（基于Cloudflare）

这是最核心的一步，因为你需要有自己的控制中心。别担心，即使你不是DevOps专家，按照步骤也能完成。

第一步：准备工作

1. 注册一个 Cloudflare 账户。如果你已经有账户，直接登录。
2. 准备一个域名（可以是免费的子域名，比如xxx.pages.dev），并将其DNS托管到Cloudflare。这一步是使用Workers和D1所必需的。
3. 在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文件来存储敏感信息（该文件已被.gitignore）：

TELEGRAM_BOT_TOKEN="你的Bot Token"

第三步：创建Cloudflare资源

1. 创建D1数据库：

   npx wrangler d1 create claw-diary-db

   执行成功后，命令行会输出database_id和database_name。将database_id填回wrangler.toml文件中的对应位置。
2. 初始化数据库表结构：查看项目schema.sql文件，使用Wrangler执行它来创建表。

   npx wrangler d1 execute claw-diary-db --file=./schema.sql

3. 创建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 "url=https://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。 运行安装程序，按照指引完成安装。安装过程通常会在系统托盘创建一个常驻图标。

第二步：首次运行与配置

1. 启动claw-diary本地代理。首次运行会弹出一个配置向导窗口。
2. 关键配置项：
   • Cloudflare Worker URL：填入你上一步部署获得的地址，例如https://my-claw-diary.your-account.workers.dev。
   • Telegram Username：输入你的Telegram用户名（不带@），这用于云端验证审批请求的来源是否合法。
   • Agent Integration：选择你要监控的AI代理。通常支持：
     • Cursor：如果安装了Cursor，代理会自动检测并注入钩子。
     • MCP（Model Context Protocol） Server：对于支持MCP协议的AI工具（如某些Claude桌面端），你需要配置MCP服务器的连接地址和密钥。
     • 通用系统监控：一个更底层的模式，尝试监控所有进程的特定系统调用（如文件删除、网络连接），但可能误报率较高，需要精细调整规则。
3. 保存配置并重启代理。此时，本地代理会尝试与你的云端Worker建立连接，并向你的Telegram Bot发送一条测试消息（如“claw-diary已成功连接”）。收到这条消息，证明整个链路已经打通。

第三步：验证与测试

1. 打开你配置的AI代理（如Cursor），尝试执行一个明确的高风险操作，例如在终端里输入一个删除测试文件的命令，或者让AI助手执行一个包含fs.unlink（Node.js删除文件）的代码。
2. 立即检查你的Telegram。你应该在几秒内收到一条审批请求。
3. 点击“批准”或“拒绝”，观察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" # 仅记录，不拦截也不需审批

策略调优思路：

1. 从宽到严：初期可以先设置较宽松的策略，主要拦截明确的删除命令和敏感路径的写入。运行一段时间后，分析时间线日志，看看AI代理通常访问哪些路径、执行哪些命令，再逐步收紧策略。
2. 基于角色/代理的差异化策略：你可以为“代码生成助手”和“数据分析助手”设置不同的策略。前者可能更关注对src/目录的写入，后者则需严防对数据库凭证文件的读取。
3. 利用路径模式：熟练使用*(匹配任意字符) 和**(递归匹配) 通配符来定义范围，避免为每个具体文件写规则。

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工具

MCP（Model 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:3001（claw-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 常见问题速查表

6.2 性能优化与维护建议

1. 数据库优化：

   • 定期清理：在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);

2. Worker逻辑优化：

   • 异步处理：对于非实时关键路径，如发送非紧急通知、写入次要日志，使用waitUntil()API使其在响应返回后异步执行，不阻塞主请求。
   • 缓存静态配置：将安全策略规则等不常变化的数据缓存在Worker的全局变量或KV中，避免每次请求都从D1读取。

3. 本地代理资源占用：正常情况下，本地代理内存占用应小于50MB。如果发现异常增高，检查是否开启了“通用系统监控”模式，该模式可能产生大量事件。调整为更精确的、基于特定工具（如Cursor）的集成模式。

4. 安全加固：

   • Telegram Token保密：如前所述，使用环境变量或Cloudflare Secrets管理Token。
   • 限制Worker访问：可以在Worker的触发器中设置路由限制，或通过简单的Token认证，确保只有你的本地代理可以调用核心API。
   • 定期更新：关注项目GitHub的Release，及时更新本地代理和Worker代码，以获取安全补丁和新功能。

经过一段时间的深度使用，claw-diary已经从最初的一个安全工具，变成了我理解和优化AI工作流不可或缺的“观察窗”。它带来的安心感，让我能更放手地让AI代理去处理复杂任务，而我知道，有一双可靠的眼睛和一道坚实的保险杠在守护着。如果你也在探索AI辅助编程或自动化，强烈建议你花点时间部署它，这份对控制感的投资，绝对物超所值。