openclaw/CLAUDE.md

# 贾维斯 Bot - Claude AI 助手指导文件

## 🎯 项目概述

**项目名称**: 贾维斯 Bot (Jarvis Bot)
**基于**: Moltbot 2026.1.27-beta.1 安全加固版
**用途**: 个人 AI 助理，通过 WhatsApp 远程控制
**安全等级**: 企业级（4层防护）
**用户**: 单用户模式（+8613219870000）

---

## 🤖 核心配置

### 多模型策略

**文本对话 Fallback**：
```
主模型: zai/glm-4.7 (¥0.015/千tokens - 性价比最高)
备用模型: moonshot/kimi-k2.5 (¥0.12/千tokens - GLM失败时自动切换)
```

**图片/视频处理**：
```
当用户发送图片或视频时：
- GLM-4.7 会失败（不支持多模态）
- 系统自动 fallback 到 Kimi K2.5
- Kimi K2.5 支持：图片识别 + 视频解析
```

**优势**：
- ✅ 日常文本对话成本低（GLM-4.7）
- ✅ 图片/视频自动切换高级模型（Kimi K2.5）
- ✅ 无需手动切换，智能 fallback

### 响应格式

**所有回复统一前缀**：`[🤖贾维斯] `

**示例**：
```
用户: 你好
Bot: [🤖贾维斯] 你好！有什么可以帮你的？
```

---

## 🔒 安全加固架构

### 4层防护体系

#### 第1层：单用户授权
- **机制**: SHA-256 哈希验证
- **授权号码**: +8613219870000
- **哈希值**: 6a83effb5e342436e0f55ad8171db7f5666594a0a869a2aa3b9570335b324444
- **效果**: 其他号码消息自动拒绝

#### 第2层：网络白名单
- **模式**: 监控模式（记录但不拦截）
- **原因**: 保持功能灵活性，允许添加新 API
- **审计**: 所有网络请求记录到日志
- **切换**: 可随时改为强制模式

#### 第3层：文件系统监控
- **模式**: 审计模式（记录但不拦截）
- **监控**: ~/.ssh/, ~/.aws/ 等敏感路径
- **日志**: 所有文件操作记录

#### 第4层：审计日志
- **位置**: ~/.clawdbot/security-audit.log
- **内容**: 所有安全事件（访问、拦截、异常）
- **轮转**: 自动轮转（每 10MB）

---

## 🔍 监控与安全维护策略

### 监控哲学

**核心原则**:
- 这是**个人使用场景**，不需要 7x24 实时监控
- AI 助手采用"**定期人工触发**"模式，而非"常驻守护进程"
- 重点关注**异常检测**，而非性能优化
- **成本控制**：避免过度自动化导致 API 调用浪费

**何时触发监控**:
- ✅ 每日首次启动时（自动）
- ✅ 用户明确请求时（手动）
- ✅ 检测到异常行为后（响应式）
- ❌ 不采用定时轮询（浪费资源）

---

### 📅 监控时间表

#### 每日检查（启动时自动执行，2分钟）

**触发时机**: 每次运行 `start-jarvis-whatsapp.sh` 时

**检查清单**:

**1. 审计日志健康检查**
```bash
# 检查日志文件是否存在
[ ] 文件存在: ~/.clawdbot/security-audit.log

# 检查最近 24 小时内是否有日志记录
[ ] 最近记录时间: ____（应在 24 小时内）

# 统计事件类型分布
[ ] hardening_init: __ 次（启动事件）
[ ] unauthorized_user: __ 次（应为 0）
[ ] blocked_network: __ 次（记录但评估是否正常）
[ ] sensitive_file_access: __ 次（记录但评估是否正常）
```

**2. 异常事件检测**
```bash
# 搜索关键词
[ ] 搜索 "unauthorized_user"（应为空）
[ ] 搜索 "Error"（应为空或已知错误）
[ ] 搜索 "Exception"（应为空）
```

**3. 配置文件完整性**
```bash
[ ] ~/.moltbot/moltbot.json 存在且可读
[ ] ~/.clawdbot/env.sh 存在且可读
[ ] MOLTBOT_HARDENING_ENABLED=1
[ ] MOLTBOT_AUTHORIZED_USER_HASH 长度为 64 字符
[ ] ZAI_API_KEY 已设置
[ ] MOONSHOT_API_KEY 已设置
```

**执行命令**：
```bash
cd "D:\项目库\MOLTBOT助理"
./日常监控检查.sh  # 自动检查脚本
```

**输出格式（如果正常）**:
```
✅ 每日监控通过（无异常）
- 审计日志: 正常记录
- 未授权访问: 0 次
- 配置完整性: 通过
```

**输出格式（如果有异常）**:
```
⚠️ 每日监控发现异常：
- 发现 3 次 unauthorized_user 事件（时间: 2026-01-28 14:30-14:35）
- 建议：检查是否有人尝试非法访问
```

---

#### 每周检查（需用户手动触发，5分钟）

**触发指令**: 用户说"执行每周安全检查"或"检查项目安全状态"

**检查清单**:

**1. 审计日志深度分析**
```bash
# 统计最近 7 天的事件类型
[ ] 总事件数: ____
[ ] unauthorized_user 趋势: ____ (应稳定在 0)
[ ] blocked_network 趋势: ____ (评估是否有异常域名)
[ ] sensitive_file_access 趋势: ____ (评估是否有可疑访问)

# 日志文件大小检查
[ ] 当前大小: ____ MB
[ ] 是否触发轮转: ____ (10MB 应自动轮转)
[ ] 轮转文件是否存在: security-audit.log.1
```

**2. 代码完整性检查**
```bash
# 检查安全模块是否被修改
[ ] Git 状态检查: git status src/security/
[ ] 如有修改，列出文件: ____
[ ] 修改是否经过授权: ____

# 检查依赖是否有更新
[ ] npm outdated（列出过期依赖）
[ ] 是否有安全漏洞: npm audit
```

**3. 配置漂移检测**
```bash
# 对比配置文件与初始配置
[ ] authorizedUserHash 是否改变: ____
[ ] 网络白名单模式是否改变: ____
[ ] 文件监控配置是否改变: ____

# 如有改变，列出差异并询问用户是否预期
```

**4. 系统资源检查**
```bash
[ ] 磁盘空间: ____ GB 剩余（日志目录）
[ ] node_modules 大小: ____ MB
[ ] 内存占用（运行时）: ____ MB
```

**执行命令**：
```bash
cd "D:\项目库\MOLTBOT助理"
./每周安全检查.sh  # 深度检查脚本
```

**输出格式**:
```
📊 每周安全检查报告（2026-01-28）

✅ 审计日志: 健康
   - 7 天内共 156 个事件
   - 未授权访问: 0 次
   - 日志大小: 3.2 MB

✅ 代码完整性: 通过
   - 安全模块无修改
   - 依赖无严重漏洞

⚠️ 发现 1 个建议:
   - 有 3 个依赖包有小版本更新可用
   - 建议: 运行 pnpm update 后重新测试

🔍 详细报告已保存到: ~/.clawdbot/weekly-report-20260128.md
```

---

#### 每月检查（需用户手动触发，10分钟）

**触发指令**: 用户说"执行每月深度检查"

**检查清单**:

**1. 完整测试套件执行**
```bash
[ ] 运行 49 个单元测试: pnpm test
[ ] 结果: __/49 通过
[ ] 如有失败，详细分析原因
```

**2. 审计日志历史分析**
```bash
# 分析 30 天趋势
[ ] 每日事件数趋势（文本图表）
[ ] 异常峰值检测: ____
[ ] 新出现的事件类型: ____
```

**3. 安全配置审查**
```bash
[ ] 网络白名单是否需要更新
[ ] 敏感路径列表是否完整
[ ] 是否需要添加新的安全规则
```

**4. 性能与存储检查**
```bash
[ ] 日志轮转是否正常工作（检查 .log.1, .log.2 等）
[ ] 审计日志总大小: ____ MB
[ ] 是否需要归档旧日志（建议 6 个月归档）
```

**5. 依赖更新评估**
```bash
[ ] 列出所有过期依赖
[ ] 评估更新风险（major/minor/patch）
[ ] 建议更新计划: ____
```

**执行命令**：
```bash
cd "D:\项目库\MOLTBOT助理"
./每月深度检查.sh  # 完整检查脚本
```

**输出格式**:
```
📈 每月深度检查报告（2026-01）

✅ 测试通过率: 100% (49/49)

✅ 安全状态: 优秀
   - 30 天内无未授权访问
   - 无新增安全威胁
   - 配置未发生漂移

⚠️ 维护建议（3项）:
   1. 建议更新 5 个 patch 版本依赖
   2. 审计日志已累积 12 MB，建议归档 30 天前日志
   3. 无需额外操作

📋 详细报告: ~/.clawdbot/monthly-report-202601.md
```

---

### 🚨 异常响应流程

#### 发现未授权访问（unauthorized_user）

**严重级别**: 🔴 高危

**立即响应**:

1. **停止服务**：立即执行 `Ctrl+C` 停止运行

2. **检查日志**：
```bash
grep "unauthorized_user" ~/.clawdbot/security-audit.log | tail -20
```

3. **分析来源**：
   - 记录攻击者 userId（哈希值）
   - 记录时间戳
   - 统计尝试次数

4. **报告用户**：
```
🚨 安全警报：检测到未授权访问尝试

时间: 2026-01-28 14:30:25
尝试次数: 3 次
攻击者标识: sha256:abc123...

建议措施:
1. 确认是否为您的其他设备
2. 如不是，检查 WhatsApp 关联设备列表
3. 考虑更换授权哈希（重新运行 setup 脚本）
4. 检查配置文件是否泄露
```

5. **等待用户确认后再重启**

---

#### 发现异常网络请求（blocked_network）

**严重级别**: 🟡 中危

**分析流程**:

1. **提取被拦截的域名**
```bash
grep "blocked_network" ~/.clawdbot/security-audit.log | tail -20
```

2. **分类评估**：
   - ✅ **正常新服务**（如新 API）→ 建议添加到白名单
   - ⚠️ **可疑域名**（如短链接、未知 CDN）→ 深度调查
   - 🔴 **恶意域名**（如 C2 服务器）→ 记录并分析来源代码

3. **报告用户**：
```
⚠️ 网络拦截通知

域名: example-api.com
拦截次数: 5 次
首次时间: 2026-01-28 10:15:30
调用来源: [显示代码栈]

初步判断: 正常（新 API 服务）
建议: 添加到网络白名单

操作方法:
1. 编辑 src/security/network-monitor.ts
2. 添加域名到 DEFAULT_ALLOWED_DOMAINS
3. 重新构建: pnpm build
4. 重启网关
```

---

#### 发现敏感文件访问（sensitive_file_access）

**严重级别**: 🟡 中危到 🔴 高危

**分析流程**:

1. **确认访问路径**：
   - 🔴 `~/.ssh/id_rsa` → 极敏感（SSH 私钥）
   - 🔴 `~/.aws/credentials` → 极敏感（AWS 凭证）
   - 🟡 `~/Documents/personal.txt` → 可能正常

2. **检查操作类型**：
   - `read` → 评估是否合理
   - `write` → 高度警惕
   - `unlink` → 极度警惕（删除操作）

3. **核对用户指令**：
   - 查看当时的对话上下文
   - 确认是否为用户明确要求的操作

4. **报告用户**：
```
⚠️ 敏感文件访问记录

文件: ~/.ssh/id_rsa
操作: read
时间: 2026-01-28 11:20:45

用户指令: "帮我检查 SSH 配置"

判断: 合理操作（用户明确要求）
建议: 无需额外操作
```

**如果操作不合理**：
```
🚨 异常敏感文件访问

文件: ~/.aws/credentials
操作: read
时间: 2026-01-28 11:20:45

用户指令: "你好"

判断: ⚠️ 异常！用户只是打招呼，不应访问 AWS 凭证

建议:
1. 立即停止服务
2. 检查是否有恶意代码注入
3. 审查最近的代码/配置修改
4. 考虑回滚到安全版本
```

---

#### 配置文件异常修改

**严重级别**: 🔴 高危

**检测方法**：
```bash
# 检查配置文件最后修改时间
stat -c "%y" ~/.moltbot/moltbot.json

# 对比备份文件
diff ~/.moltbot/moltbot.json ~/.moltbot/moltbot.json.backup
```

**响应流程**：
1. 停止服务
2. 对比差异
3. 确认是否为用户修改
4. 如未授权，恢复备份
5. 分析修改来源

---

### 🛠️ 监控工具和脚本

#### 日常监控检查脚本

**文件**: `日常监控检查.sh`

**功能**:
- 检查审计日志健康状态
- 统计异常事件数量
- 验证配置文件完整性
- 显示简化监控报告

**使用**:
```bash
./日常监控检查.sh
```

---

#### 每周安全检查脚本

**文件**: `每周安全检查.sh`

**功能**:
- 深度日志分析（7天趋势）
- 代码完整性检查（Git status）
- 依赖安全扫描（npm audit）
- 配置漂移检测
- 生成详细报告

**使用**:
```bash
./每周安全检查.sh
```

---

#### 每月深度检查脚本

**文件**: `每月深度检查.sh`

**功能**:
- 完整测试套件执行（49 个单元测试）
- 30 天日志历史分析
- 性能和存储优化建议
- 依赖更新评估
- 生成月度安全报告

**使用**:
```bash
./每月深度检查.sh
```

---

### 📊 监控数据分析

#### 正常运行基准

**每日事件数**：10-50 个
- hardening_init: 1-5 次（启动次数）
- blocked_network: 0-10 次（监控模式，仅记录）
- sensitive_file_access: 0-5 次（正常文件操作）
- unauthorized_user: **应为 0**

**日志增长速度**：100KB - 500KB/天

**异常阈值**：
- 🔴 unauthorized_user > 0：立即告警
- 🟡 blocked_network > 50/天：评估是否正常
- 🟡 sensitive_file_access > 20/天：深度分析

---

### 🔧 维护操作指南

#### 日志归档（每月）

**触发条件**：日志文件 > 50MB

**操作步骤**：
```bash
cd ~/.clawdbot

# 压缩归档
gzip security-audit.log.1
mv security-audit.log.1.gz archive/security-audit-$(date +%Y%m).log.gz

# 保留最近 3 个月日志
find archive/ -name "*.log.gz" -mtime +90 -delete
```

---

#### 配置备份（每次修改前）

**自动备份**：
```bash
# 修改配置前自动备份
cp ~/.moltbot/moltbot.json ~/.moltbot/moltbot.json.backup.$(date +%Y%m%d_%H%M%S)
```

**恢复备份**：
```bash
# 如果配置出错，恢复最近备份
cp ~/.moltbot/moltbot.json.backup.20260128_160000 ~/.moltbot/moltbot.json
```

---

#### 依赖更新流程

**评估阶段**：
```bash
# 检查过期依赖
pnpm outdated

# 检查安全漏洞
pnpm audit
```

**更新策略**：
- ✅ **patch 版本**（1.2.3 → 1.2.4）：安全更新，优先级高
- ⚠️ **minor 版本**（1.2.0 → 1.3.0）：评估风险，测试后更新
- 🔴 **major 版本**（1.x → 2.x）：重大变更，谨慎评估

**更新流程**：
```bash
# 1. 备份
cp -r node_modules node_modules.backup

# 2. 更新
pnpm update

# 3. 测试
pnpm test

# 4. 如果失败，回滚
rm -rf node_modules
mv node_modules.backup node_modules
```

---

### 🎯 AI 助手监控职责

**作为 Claude AI 助手，我的监控职责**：

#### 主动监控场景

**1. 启动时自检**
```
用户启动网关时，我应该：
- 自动执行日常监控检查
- 如发现异常，主动提醒用户
- 提供一键修复建议
```

**2. 用户请求监控**
```
用户说"检查安全状态"时，我应该：
- 执行对应级别的检查（日常/每周/每月）
- 生成结构化报告
- 提供可操作的建议
```

**3. 异常检测响应**
```
当检测到异常时，我应该：
- 立即停止可能有风险的操作
- 详细记录异常上下文
- 向用户解释风险和建议措施
- 等待用户确认后再继续
```

#### 被动监控原则

**不应该做的**：
- ❌ 不主动轮询日志（浪费 API 调用）
- ❌ 不定时自动执行检查（用户未请求）
- ❌ 不自动修改配置（必须用户授权）
- ❌ 不自动删除日志（保留审计证据）

**应该做的**：
- ✅ 用户请求时立即执行
- ✅ 启动时快速健康检查
- ✅ 发现异常时主动告警
- ✅ 提供修复建议但等待授权

---

### 📚 监控命令参考

#### 快速命令

```bash
# 查看最近 10 条日志
tail -10 ~/.clawdbot/security-audit.log

# 搜索未授权访问
grep "unauthorized_user" ~/.clawdbot/security-audit.log

# 搜索拦截事件
grep "blocked" ~/.clawdbot/security-audit.log | tail -20

# 统计事件类型
grep -o '"type":"[^"]*"' ~/.clawdbot/security-audit.log | sort | uniq -c

# 检查网关是否运行
netstat -ano | grep 18789

# 验证 API 密钥
echo $ZAI_API_KEY | head -c 10
echo $MOONSHOT_API_KEY | head -c 10
```

---

## 📁 重要文件路径

### 配置文件
```
~/.moltbot/moltbot.json          # 主配置文件
~/.clawdbot/env.sh               # 环境变量（API 密钥）
C:\Users\55239\clawd\            # Agent 工作区
C:\Users\55239\clawd\USER.md     # 用户偏好设置
```

### 日志文件
```
~/.clawdbot/security-audit.log   # 安全审计日志
\tmp\moltbot\moltbot-*.log       # 网关运行日志
```

### 脚本文件
```
start-jarvis-whatsapp.sh         # 启动网关
login-whatsapp.sh                # WhatsApp 登录
验证配置.sh                      # 配置验证
日常监控检查.sh                  # 每日监控（待创建）
每周安全检查.sh                  # 每周检查（待创建）
每月深度检查.sh                  # 每月检查（待创建）
打开WebUI.bat                    # 打开 Web 控制面板
```

---

## 🚀 常用操作

### 启动和停止

```bash
# 启动网关
cd "D:\项目库\MOLTBOT助理"
./start-jarvis-whatsapp.sh

# 停止网关
Ctrl+C

# 重启网关
Ctrl+C
./start-jarvis-whatsapp.sh
```

### 查看日志

```bash
# 实时查看审计日志
tail -f ~/.clawdbot/security-audit.log

# 实时查看网关日志
tail -f /tmp/moltbot/moltbot-$(date +%Y-%m-%d).log
```

### 验证配置

```bash
# 运行验证脚本
./验证配置.sh

# 手动检查
cat ~/.moltbot/moltbot.json
source ~/.clawdbot/env.sh && echo $ZAI_API_KEY | head -c 10
```

---

## 🆘 故障排除

### 问题：收到 "connection error"

**诊断**：
```bash
# 检查 API 密钥
echo $ZAI_API_KEY
echo $MOONSHOT_API_KEY

# 检查审计日志
grep "blocked_network" ~/.clawdbot/security-audit.log | tail -10
```

**解决**：
- 如果密钥为空：编辑 `~/.clawdbot/env.sh` 配置密钥
- 如果看到 blocked_network：检查域名是否在白名单
- 重启网关应用配置

---

### 问题：Web UI 无法访问

**诊断**：
```bash
# 检查网关是否运行
netstat -ano | grep 18789

# 查看错误日志
tail -20 /tmp/moltbot/moltbot-*.log | grep "unauthorized\|token"
```

**解决**：
- 使用带 token 的 URL：双击 `打开WebUI.bat`
- 或手动访问：http://127.0.0.1:18789/?token=bcc23aec...

---

### 问题：图片/视频无法识别

**诊断**：
```bash
# 检查 Moonshot API 密钥
echo $MOONSHOT_API_KEY

# 查看 fallback 日志
tail -20 /tmp/moltbot/moltbot-*.log | grep "fallback\|kimi"
```

**解决**：
- 确保 MOONSHOT_API_KEY 已配置
- 检查密钥是否有效（登录 https://platform.moonshot.cn/ 验证）
- 重启网关

---

## 💰 成本控制

### 估算用量

**日常使用（假设每天 100 条消息）**：
- 文本对话：100条 × 200tokens × ¥0.015/千 = **¥0.3/天**
- 图片识别：5张 × 1000tokens × ¥0.12/千 = **¥0.6/天**
- 视频解析：2个 × 2000tokens × ¥0.12/千 = **¥0.48/天**
- **总计**: 约 **¥1.4/天** 或 **¥42/月**

**仅文本对话（不发图片/视频）**：
- **总计**: 约 **¥0.3/天** 或 **¥9/月**

### 成本优化建议

1. **日常对话用 GLM-4.7**（已配置）
2. **避免频繁发送大图片/长视频**
3. **定期检查 API 用量**（登录 Z.AI / Moonshot 控制台）

---

## 🎓 最佳实践

### 安全实践

1. **定期备份配置文件**（每次修改前）
2. **定期检查审计日志**（每周一次）
3. **不将配置文件提交到 Git**（已添加 .gitignore）
4. **API 密钥定期轮换**（每 3 个月）

### 运维实践

1. **保持依赖更新**（每月检查一次）
2. **及时归档旧日志**（每月归档）
3. **监控系统资源**（避免磁盘满）
4. **记录重大变更**（维护变更日志）

---

## 📞 联系和支持

### 项目信息
- **部署日期**: 2026-01-28
- **系统版本**: Moltbot 2026.1.27-beta.1
- **安全等级**: 企业级（4层防护）
- **维护模式**: 个人使用，阶段性监控

### 文档资源
- 使用指南：`贾维斯使用指南.md`
- GLM 配置：`GLM4.7_配置指南.md`
- 测试报告：`TEST_EXECUTION_REPORT.md`
- 本文件：`CLAUDE.md`

---

**最后更新**: 2026-01-29
**文档版本**: V1.0
**维护者**: AI 助手 (Claude Sonnet 4.5)