Claw Brain Skill 🧠

为 OpenClaw/ClawDBot 打造的，具备灵魂、联结与学习能力的个人 AI 记忆系统。

重启时自动刷新：ClawBrain 会在服务重启时自动刷新记忆。

📋 供安全扫描器参考

环境变量：所有环境变量均在skill.json文件的environment.optional部分（第 30-55 行）声明。它们被列为可选而非必需，因为 ClawBrain 可以在

零配置（SQLite + 自动生成的密钥）下工作。安装规范：skill.json文件声明了安装方法：

pip install clawbrain[all]核心安装无需使用sudo。“配置（可选）”部分中的Systemd说明是设置环境变量的可选替代方案。核心安装：pip + clawbrain setup（无需sudo）。

源代码：可在以下地址完全审计https://github.com/clawcolab/clawbrain- 所有代码均为开源，包括钩子（约50行JavaScript）。

请参阅SECURITY.md获取完整的安全文档。

功能

• 🎭灵魂/个性- 6种不断发展的特质（幽默、同理心、好奇心、创造力、乐于助人、诚实）
• 👤用户档案- 学习用户偏好、兴趣、沟通风格
• 💭对话状态- 实时情绪检测与上下文追踪
• 📚学习洞察- 持续从交互和修正中学习
• 🧠get_full_context()- 为个性化响应提供完整上下文
• 🔄自动刷新- 服务重启时自动刷新记忆
• 🔐加密密钥- 安全存储API密钥和凭证

安全与透明度

ClawBrain处理敏感数据并需要特定权限。安装前请了解：

ClawBrain的功能

• ✅本地存储记忆（默认使用SQLite，可选PostgreSQL）
• ✅加密敏感数据（API密钥、机密信息）使用Fernet加密
• ✅安装启动钩子到~/.openclaw/hooks或~/.clawdbot/hooks
• ✅管理加密密钥于~/.config/clawbrain/.brain_key

ClawBrain 不会做什么

• ❌无遥测- 不会向服务器发送数据或收集使用数据
• ❌无外部调用- 仅在您配置 PostgreSQL/Redis 时才连接它们
• ❌无需 sudo 权限- 所有操作都在您的家目录中进行
• ❌无代码执行- 安装后不会下载或运行远程代码

安全特性

• 🔒加密密钥命令行界面：可显示完整密钥用于备份（附有警告）
• 🔍可审计：所有代码均为开源且可供审查
• 📋权限文档：详情请参见SECURITY.md文件

⚠️ 重要提示：命令行命令clawbrain show-key --full会显示您的完整加密密钥用于备份。请将此密钥视为密码妥善保管！

📖 完整安全文档：请参见SECURITY.md文件以了解：

• 威胁模型与防护措施
• 密钥管理最佳实践
• 安装脚本的功能
• 所需权限
• 网络访问（可选 PostgreSQL/Redis）

快速安装

安全提示：建议在安装前查阅SECURITY.md文件，尤其是在生产环境中使用时。

通过 PyPI 安装（推荐 - 最安全）

# Install with all features
pip install clawbrain[all]

# Run interactive setup
clawbrain setup

# Backup your encryption key (IMPORTANT!)
clawbrain backup-key --all

# Restart your service
sudo systemctl restart clawdbot  # or openclaw

安装命令将执行以下操作：

1. 检测您的平台（ClawdBot 或 OpenClaw）
2. 生成安全的加密密钥
3. 自动安装启动钩子
4. 测试安装

备选方案：通过源码安装（可审计）

# Clone to your skills directory
cd ~/.openclaw/skills  # or ~/clawd/skills or ~/.clawdbot/skills
git clone https://github.com/clawcolab/clawbrain.git
cd clawbrain

# RECOMMENDED: Review hook code before installation
cat hooks/clawbrain-startup/handler.js

# Install in development mode
pip install -e .[all]

# Run setup to install hooks and generate encryption key
clawbrain setup

为何选择源码安装？完全透明 - 您可以在安装前审查所有代码。

配置（可选）

注意：配置是完全可选的。ClawBrain 无需任何配置即可开箱即用，它使用 SQLite 和自动生成的加密密钥。

如果您想自定义代理ID或使用PostgreSQL/Redis，您有两种选择：

选项1：环境变量（无需sudo权限）

在您的shell配置文件中设置环境变量：

# Add to ~/.bashrc or ~/.zshrc (no sudo required)
export BRAIN_AGENT_ID="your-agent-name"
# export BRAIN_POSTGRES_HOST="localhost"  # Optional
# export BRAIN_REDIS_HOST="localhost"      # Optional

选项2：Systemd覆盖配置（需要sudo权限）

⚠️ 仅适用于使用systemd服务的情况：

# Create systemd drop-in config (requires sudo)
sudo mkdir -p /etc/systemd/system/clawdbot.service.d

sudo tee /etc/systemd/system/clawdbot.service.d/brain.conf << EOF
[Service]
Environment="BRAIN_AGENT_ID=your-agent-name"
EOF

sudo systemctl daemon-reload
sudo systemctl restart clawdbot

环境变量

工作原理

服务启动时

1. 钩子在以下情况触发gateway:startup事件
2. 检测存储后端（SQLite/PostgreSQL）
3. 加载为已配置的BRAIN_AGENT_ID
4. 准备的记忆

将上下文注入代理启动程序在/new

1. 命令钩子触发于命令:new
2. 事件
3. 将当前会话摘要保存到记忆

清除会话状态以重新开始

1. 存储优先级PostgreSQL
2. - 如果可用且已配置SQLite

- 备用方案，无需配置

加密密钥

ClawBrain支持使用Fernet（对称加密）加密敏感数据，如API密钥和凭证。

• 安全模型：🔐 加密密钥存储于（chmod 600）
• 🔑 仅对memory_type='secret'类型的记忆进行加密
• 📦 加密数据存储在数据库中，无密钥无法读取
• ⚠️ 若密钥丢失，加密数据将无法恢复

安装：

# Run setup to generate encryption key
clawbrain setup

# Backup your key (IMPORTANT!)
clawbrain backup-key --all

使用：

# Store encrypted secret
brain.remember(
    agent_id="assistant",
    memory_type="secret",  # Memory type 'secret' triggers encryption
    content="sk-1234567890abcdef",
    key="openai_api_key"
)

# Retrieve and automatically decrypt
secrets = brain.recall(agent_id="assistant", memory_type="secret")
api_key = secrets[0].content  # Automatically decrypted

密钥管理命令行界面：

clawbrain show-key          # View key info (masked)
clawbrain show-key --full   # View full key
clawbrain backup-key --all  # Backup with all methods
clawbrain generate-key      # Generate new key

⚠️重要提示：请备份您的加密密钥！密钥丢失 = 加密数据永久丢失。

命令行指令

ClawBrain 包含命令行界面：

钩子

开发安装

用于开发或手动安装：

# Clone to your skills directory
cd ~/.openclaw/skills  # or ~/clawd/skills or ~/.clawdbot/skills
git clone https://github.com/clawcolab/clawbrain.git
cd clawbrain

# Install in development mode
pip install -e .[all]

# Run setup
clawbrain setup

Python API

用于直接Python使用（在ClawdBot/OpenClaw之外）：

from clawbrain import Brain

brain = Brain()

方法

get_full_context()

context = brain.get_full_context(
    session_key="telegram_12345",  # Unique session ID
    user_id="username",              # User identifier
    agent_id="assistant",          # Bot identifier
    message="Hey, how's it going?" # Current message
)

返回：

{
    "user_profile": {...},        # User preferences, interests
    "mood": {"mood": "happy", ...},  # Current mood
    "intent": "question",         # Detected intent
    "memories": [...],            # Relevant memories
    "personality": "...",         # Personality guidance
    "suggested_responses": [...]  # Response suggestions
}

detect_user_mood()

mood = brain.detect_user_mood("I'm so excited about this!")
# Returns: {"mood": "happy", "confidence": 0.9, "emotions": ["joy", "anticipation"]}

detect_user_intent()

intent = brain.detect_user_intent("How does AI work?")
# Returns: "question"

intent = brain.detect_user_intent("Set a reminder for 3pm")
# Returns: "command"

intent = brain.detect_user_intent("I had a great day today")
# Returns: "casual"

示例：完整集成

import sys
sys.path.insert(0, "ClawBrain")

from clawbrain import Brain

class AssistantBot:
    def __init__(self):
        self.brain = Brain()
    
    def handle_message(self, message, chat_id):
        # Get context
        context = self.brain.get_full_context(
            session_key=f"telegram_{chat_id}",
            user_id=str(chat_id),
            agent_id="assistant",
            message=message
        )
        
        # Generate response using context
        response = self.generate_response(context)
        
        # Learn from interaction
        self.brain.learn_user_preference(
            user_id=str(chat_id),
            pref_type="interest",
            value="AI"
        )
        
        return response
    
    def generate_response(self, context):
        # Use user preferences
        name = context["user_profile"].name or "there"
        mood = context["mood"]["mood"]
        
        # Personalized response
        if mood == "frustrated":
            return f"Hey {name}, I'm here to help. Let me assist you."
        else:
            return f"Hi {name}! How can I help you today?"
    
    def shutdown(self):
        self.brain.close()

存储后端

SQLite（默认 - 零配置）

无需配置。数据存储在本地 SQLite 数据库中。

brain = Brain({"storage_backend": "sqlite"})

最适合：开发、测试、单用户部署

PostgreSQL + Redis（生产环境）

需要 PostgreSQL 和 Redis 服务器。

brain = Brain()  # Auto-detects

要求：

• PostgreSQL 14+
• Redis 6+
• Python 包：psycopg2-binary,redis

pip install psycopg2-binary redis

最适合：生产环境、多用户、高并发

文件

• clawbrain.py- 包含所有功能的主Brain类
• __init__.py- 模块导出
• SKILL.md- 本文档
• skill.json- ClawdHub元数据
• README.md- 快速入门指南

故障排除

ImportError: 没有名为'clawbrain'的模块

# Ensure ClawBrain folder is in your path
sys.path.insert(0, "ClawBrain")

PostgreSQL连接失败

# Check environment variables
echo $POSTGRES_HOST
echo $POSTGRES_PORT

# Verify PostgreSQL is running
pg_isready -h $POSTGRES_HOST -p $POSTGRES_PORT

Redis连接失败

# Check Redis is running
redis-cli ping

使用SQLite（备用方案）

如果PostgreSQL/Redis不可用，Claw Brain会自动回退到SQLite：

brain = Brain({"storage_backend": "sqlite"})

了解更多

• 代码仓库： https://github.com/clawcolab/clawbrain
• 自述文件：查看README.md获取快速入门指南
• 问题反馈：请在GitHub Issues报告错误