Files
my-project/doc/OPENCLAW_CONFIG_STANDARD.md
T

742 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🤖 OpenClaw 机器人配置方案标准文件
> 版本: v1.0
> 创建日期: 2026-02-07
> 制定者: 2号机 (守护者)
> **核心原则**: 稳定优先 > 功能保证
---
## 📋 目录
1. [配置优先级](#配置优先级)
2. [核心配置](#核心配置)
3. [功能配置](#功能配置)
4. [监控体系](#监控体系)
5. [故障恢复](#故障恢复)
6. [部署清单](#部署清单)
---
## 🎯 配置优先级
### P0 - 核心配置 (必须配置)
| 优先级 | 配置项 | 状态 | 说明 |
|--------|--------|------|------|
| P0-1 | Gateway 运行配置 | ✅ | 绑定模式、端口、认证 |
| P0-2 | 代理配置 | ✅ | NO_PROXY、系统代理 |
| P0-3 | 模型提供商 | ✅ | MiniMax/DeepSeek/Ollama |
| P0-4 | 会话管理 | ✅ | 会话文件路径、大小监控 |
| P0-5 | 监控告警 | ✅ | 系统监控脚本、Telegram 告警 |
| P0-6 | 日志管理 | ✅ | 日志级别、文件轮转 |
### P1 - 重要配置 (强烈建议)
| 配置项 | 说明 |
|--------|------|
| 安全配置 | API Key 加密、访问控制 |
| 备份策略 | 会话文件自动备份 |
| 健康检查 | 定期健康检查脚本 |
### P2 - 功能配置 (可选功能)
| 功能 | 优先级 | 说明 |
|------|--------|------|
| **浏览器** | P2 | 网页浏览、内容抓取 |
| **人格化** | P2 | Agent 记忆、性格塑造 |
| RSS 订阅 | P2 | 内容聚合 |
| TTS 语音 | P2 | 文本转语音 |
---
## ⚙️ 核心配置
### 1. Gateway 运行配置
```json
{
"gateway": {
"binding": "0.0.0.0:18789",
"auth": {
"enabled": true,
"token": "${GATEWAY_TOKEN}"
},
"cors": {
"enabled": false
}
}
}
```
**配置原则:**
- 绑定地址:内网使用 0.0.0.0,外网使用 127.0.0.1
- 认证:生产环境必须启用
- CORS:仅开发环境开启
### 2. 代理配置
```bash
# /etc/environment
NO_PROXY="localhost,127.0.0.1,192.168.0.66"
no_proxy="localhost,127.0.0.1,192.168.0.66"
HTTP_PROXY="http://192.168.0.66:7890"
HTTPS_PROXY="http://192.168.0.66:7890"
```
**启动命令:**
```bash
NO_PROXY="localhost.0.1,127.0,192.168.0.66" openclaw gateway restart
```
### 3. 模型提供商配置
```json
{
"providers": {
"minimax": {
"models": {
"default": "minimax-minimax"
}
},
"deepseek": {
"models": {
"default": "deepseek-chat"
}
},
"ollama": {
"remote": {
"baseUrl": "http://localhost:11434/v1"
}
}
}
}
```
**配置原则:**
- 主力模型:MiniMax (原生推理)
- 备用模型:DeepSeek (成本低)
- 本地模型:Ollama (离线备用)
### 4. 会话管理配置
```json
{
"sessions": {
"path": "/root/.openclaw/agents/main/sessions",
"maxSize": "8MB",
"warnSize": "5MB",
"autoArchive": true
}
}
```
**监控阈值:**
| 条件 | 动作 |
|------|------|
| ≥5MB | 发送警告日志 |
| ≥8MB | 发送 Telegram 告警 |
| 完成后 | 建议开新会话 |
### 5. 监控告警配置
#### 5.1 系统监控脚本
```bash
# /root/.openclaw/scripts/system-monitor.sh
#!/bin/bash
# 监控间隔 (秒)
INTERVAL=300
# 告警阈值
CPU_THRESHOLD=80
MEM_THRESHOLD=85
DISK_THRESHOLD=90
# Telegram 告警
TELEGRAM_TOKEN="8202664888:AAE0UyCFJJBLC8notdmT42XOJRBoWLJ6XOI"
CHAT_ID="5117446326"
```
#### 5.2 会话文件监控
```bash
# 检查会话文件大小
SESSION_DIR="/root/.openclaw/agents/main/sessions"
WARN_SIZE=8388608 # 8MB
for session_file in "$SESSION_DIR"/*.jsonl; do
size=$(stat -f%z "$session_file" 2>/dev/null || stat -c%s "$session_file" 2>/dev/null)
if [ "$size" -gt "$WARN_SIZE" ]; then
# 发送 Telegram 告警
curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_TOKEN/sendMessage" \
-d "chat_id=$CHAT_ID" \
-d "text=⚠️ 会话文件过大: $(basename $session_file) ($(expr $size / 1024 / 1024)MB)"
fi
done
```
### 6. 日志管理配置
```bash
# 日志配置
OPENCLAW_LOG_DIR="/tmp/openclaw"
OPENCLAW_LOG_LEVEL="info"
# 日志轮转 (logrotate)
# /etc/logrotate.d/openclaw
/var/log/openclaw/*.log {
daily
rotate 7
compress
delaycompress
missingok
notifempty
}
```
---
## 🎭 功能配置
> **注意**: 以下功能为 P2 优先级,不影响核心运行
### 1. 浏览器功能 (P2)
```json
{
"browser": {
"enabled": true,
"profile": "openclaw",
"timeout": 30000,
"headless": true
}
}
```
**配置原则:**
- 需要 OpenClaw Browser Extension
- 作为备用工具,不作为核心依赖
- 优先使用 web_fetch
**已知问题:**
- 2号机:OpenClaw 扩展未连接
- 替代方案:使用 web_fetch
### 2. 人格化功能 (P2)
#### 2.1 基础人格文件
```bash
# 人格文件目录结构
/root/.openclaw/identity/
├── IDENTITY.md - 身份定义 (Who am I?)
├── SOUL.md - 灵魂/性格 (Who am I becoming?)
└── USER.md - 用户偏好 (Who am I helping?)
```
#### 2.2 IDENTITY.md 模板
```markdown
# IDENTITY.md - {机器人名称}是谁?
- **Name:** {名称}
- **Code Name:** {代号}
- **Creature:** AI Assistant
- **Vibe:** {风格描述}
- **Emoji:** {表情符号}
## Core Identity
{一句话描述}
## Role
### Primary Duties
1. {职责1}
2. {职责2}
3. {职责3}
```
#### 2.3 SOUL.md 模板 (包含记忆召回规则)
```markdown
# SOUL.md - {机器人名称}的灵魂
__{风格描述}__
## Core Truths
**性格特点1** - {说明}
**性格特点2** - {说明}
**性格特点3** - {说明}
## Boundaries
- {边界1}
- {边界2}
- {边界3}
## Vibe
- {风格1}
- {风格2}
- {风格3}
## 记忆召回规则
**每次回答配置/规格类问题前,必须执行以下流程:**
### 1. 强制召回流程
回答前必须:
1. memory_search(相关关键词)
2. memory_get(相关文件)
3. 必要时读取配置文件
4. 必要时查询实际系统
5. 基于事实回答,绝不凭印象
### 2. 召回优先级
| 问题类型 | 召回来源 |
|----------|----------|
| 系统配置 | openclaw.json + 配置文档 |
| 硬件规格 | MEMORY.md + 实际查询 |
| 历史决策 | memory/YYYY-MM-DD.md |
| 用户偏好 | USER.md |
### 3. 禁止行为
- ❌ 完全凭印象回答
- ❌ 不检查记忆直接回答
- ❌ 假设应该记得
- ❌ 用大概可能回答配置问题
### 4. 正确示例
用户: X 内存多少?
我: (执行 memory_search) → 回答: 8GB DDR3
### 5. 错误示例
用户: X 内存多少?
我: 应该是 8GB 吧 (未检查记忆)
---
> 记忆是资产的保险,回答前先查阅。
```
#### 2.4 USER.md 模板
```markdown
# USER.md - {机器人名称}服务的用户
## User Context
- **Name:** {用户名}
- **Platform:** {平台}
- **ID:** {ID}
- **Timezone:** {时区}
## Notes
- {偏好1}
- {偏好2}
- {偏好3}
```
#### 2.5 快速人格配置脚本
```bash
#!/bin/bash
# configure_personality.sh <名称> <代号> <风格> <Emoji>
NAME=$1
CODE_NAME=$2
VIBE=$3
EMOJI=$4
mkdir -p /root/.openclaw/identity
# 创建人格文件...
echo "✅ $NAME 人格文件创建完成"
```
#### 2.6 配置原则
| 原则 | 说明 |
|------|------|
| 轻量化优先 | 基于文件的人格化,不依赖外部服务 |
| 记忆召回 | 回答配置类问题前必须先搜索记忆 |
| 跨会话持久化 | memory/ 目录存储长期记忆 |
---
### 3. 记忆系统方案
#### 3.1 轻量化方案 (低配置机器)
```bash
# 使用 OpenClaw 自带 Memory
openclaw memory status # 确认已启用
```
**配置:**
- 存储: SQLite
- 向量: nomic-embed-text:latest
- 适合: 2号机 (8GB RAM + HDD)
#### 3.2 memU 方案 (中配置机器)
```bash
# memU - 24/7 主动记忆
# GitHub: github.com/mem0ai/mem0
# Stars: 8.1k
# 版本: v1.4.0 (Feb 6, 2026)
pip install mem0ai
# 配置
export MEM0_API_KEY="your-key"
```
**特点:**
- Python 架构
- 主动记忆学习
- OpenClaw 替代方案
#### 3.3 MemOS 方案 (高配置机器)
```bash
# MemOS - 技能进化型记忆
# GitHub: github.com/MemTensor/MemOS
# Stars: 5k
# 版本: v2.0.4 (Jan 30, 2026)
# 官网: memtensor.ai
# Docker 部署 (青龙方案)
docker run -d -p 8000:8000 memtensor/memos:latest
```
**特点:**
- 官方 OpenClaw 插件
- +43.70% 准确率
- Neo4j + Qdrant 双存储
- 适合: 青龙 (NVMe SSD)
#### 3.4 记忆方案对比
| 方案 | 复杂度 | 资源占用 | 适合场景 |
|------|--------|----------|----------|
| **OpenClaw Memory** | 低 | ~100MB | 2号机 (轻量首选) |
| **memU** | 中 | ~200-500MB | 中配置机器 |
| **MemOS** | 高 | ~2GB | 青龙 (SSD 高配) |
---
### 4. RSS 订阅功能 (P2)
### 3. RSS 订阅功能 (P2)
```json
{
"rss": {
"enabled": false,
"feeds": [],
"interval": 3600
}
}
```
**配置原则:**
- 需要外部 HTTP 请求
- 代理不稳定时不启用
- 作为后台任务运行
### 4. TTS 语音功能 (P2)
```json
{
"tts": {
"enabled": false,
"provider": "sag",
"voice": "default"
}
}
```
**配置原则:**
- 需要 ElevenLabs API (成本)
- 仅在用户明确要求时启用
- 主要用于故事朗读
---
## 📊 监控体系
### 1. 监控指标
| 指标 | 阈值 | 告警级别 |
|------|------|----------|
| Gateway 状态 | down | 🔴 严重 |
| CPU 使用率 | >80% | 🟡 警告 |
| 内存使用率 | >85% | 🟡 警告 |
| 磁盘使用率 | >90% | 🔴 严重 |
| 会话文件大小 | >8MB | 🟡 警告 |
| 代理连接失败 | >3次 | 🟡 警告 |
### 2. 监控脚本
```bash
# /root/.openclaw/scripts/health-check.sh
#!/bin/bash
set -e
check_gateway() {
if ! pgrep -f "openclaw" > /dev/null; then
echo "🔴 Gateway 未运行"
return 1
fi
echo "✅ Gateway 运行正常"
}
check_memory() {
mem_usage=$(free | grep Mem | awk '{printf "%.1f", $3/$2 * 100}')
if (( $(echo "$mem_usage > 85" | bc -l) )); then
echo "🟡 内存使用率: ${mem_usage}%"
else
echo "✅ 内存使用率: ${mem_usage}%"
fi
}
check_sessions() {
session_count=$(ls /root/.openclaw/agents/main/sessions/*.jsonl 2>/dev/null | wc -l)
echo "📁 会话文件数量: $session_count"
}
# 运行检查
check_gateway
check_memory
check_sessions
```
### 3. Telegram 告警
```bash
# /root/.openclaw/scripts/send-alert.sh
#!/bin/bash
TELEGRAM_TOKEN="your_token"
CHAT_ID="your_chat_id"
send_alert() {
local level=$1
local message=$2
case $level in
critical)
emoji="🔴"
;;
warning)
emoji="🟡"
;;
info)
emoji="ℹ️"
;;
esac
curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_TOKEN/sendMessage" \
-d "chat_id=$CHAT_ID" \
-d "text=$emoji $message"
}
```
---
## 🔧 故障恢复
### 1. 自动恢复策略
```bash
# /root/.openclaw/scripts/auto-recovery.sh
#!/bin/bash
restart_gateway() {
echo "[$(date)] 检测到 Gateway 异常,尝试重启..."
NO_PROXY="localhost,127.0.0.1,192.168.0.66" openclaw gateway restart
sleep 5
if pgrep -f "openclaw" > /dev/null; then
echo "[$(date)] Gateway 重启成功"
send_alert info "Gateway 已自动重启"
else
echo "[$(date)] Gateway 重启失败,尝试强制重启"
pkill -9 -f openclaw
sleep 2
NO_PROXY="localhost,127.0.0.1,192.168.0.66" openclaw gateway restart
fi
}
# 检查 Gateway 是否存活
if ! pgrep -f "openclaw.*gateway" > /dev/null; then
restart_gateway
fi
```
### 2. 常见故障处理
| 故障现象 | 可能原因 | 解决方案 |
|----------|----------|----------|
| Gateway 无响应 | 内存泄漏 | 强制重启 |
| 会话文件过大 (>10MB) | Compaction 卡死 | 手动清理 |
| 代理连接失败 | 代理服务异常 | 检查代理 |
| 模型调用超时 | 网络/配置问题 | 检查配置 |
| 监控脚本报错 | awk 语法错误 | 使用 heredoc |
### 3. Compaction 处理
```bash
# 清理卡死的会话文件
cleanup_compaction() {
echo "[$(date)] 清理卡死的会话文件..."
# 查找大文件
find /root/.openclaw/agents/main/sessions -name "*.jsonl" -size +5M
# 备份大文件
timestamp=$(date +%Y%m%d_%H%M%S)
mkdir -p /root/.openclaw/backup/sessions_$timestamp
# 移动大文件到备份目录
find /root/.openclaw/agents/main/sessions -name "*.jsonl" -size +10M \
-exec mv {} /root/.openclaw/backup/sessions_$timestamp/ \;
echo "[$(date)] 已清理会话文件,备份到 $timestamp"
}
```
---
## 📦 部署清单
### 部署前检查
```bash
# 1. 检查系统要求
- [ ] Python >= 3.10
- [ ] Node.js >= 18
- [ ] 内存 >= 4GB
- [ ] 磁盘 >= 10GB
# 2. 检查依赖
- [ ] Git
- [ ] curl
- [ ] jq
- [ ] logrotate
# 3. 检查网络
- [ ] 代理可访问
- [ ] Telegram 可访问
- [ ] 模型 API 可访问
```
### 部署步骤
```bash
# 1. 安装 OpenClaw
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
# 2. 配置核心设置
cp config.example.json openclaw.json
# 编辑 openclaw.json (见核心配置)
# 3. 配置监控脚本
cp scripts/system-monitor.sh /root/.openclaw/scripts/
chmod +x /root/.openclaw/scripts/*.sh
# 4. 配置 systemd 服务
cp openclaw.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable openclaw
systemctl start openclaw
# 5. 配置 logrotate
cp openclaw.logrotate /etc/logrotate.d/
# 6. 验证部署
openclaw doctor
```
### 验证检查
```bash
# 核心功能验证
✅ Gateway 运行: pgrep -f "openclaw"
✅ 端口监听: netstat -tlnp | grep 18789
✅ 模型调用: openclaw test model
✅ Telegram 连接: openclaw telegram status
# 功能验证
✅ RSS 订阅: (可选)
✅ TTS 语音: (可选)
✅ 浏览器: (可选)
```
---
## 📈 性能基准
### 基准配置
| 组件 | 最低配置 | 推荐配置 |
|------|----------|----------|
| CPU | 2 核心 | 4 核心 |
| 内存 | 4GB | 8GB |
| 存储 | 10GB HDD | 50GB SSD |
| 网络 | 10Mbps | 100Mbps |
### 预期性能
| 指标 | 预期值 | 备注 |
|------|--------|------|
| 启动时间 | <30s | 冷启动 |
| 对话响应 | <5s | 正常负载 |
| 内存占用 | <500MB | 稳定后 |
| 并发会话 | 1-3 | 建议 |
---
## 🔒 安全基线
### 必须配置
- [ ] Gateway 认证令牌
- [ ] API Key 加密存储
- [ ] 禁止 root 运行 (除非必要)
- [ ] 防火墙规则 (仅开放必要端口)
### 建议配置
- [ ] HTTPS 终结 (使用 nginx)
- [ ] Rate Limiting
- [ ] 审计日志
- [ ] 定期安全更新
---
## 📝 版本历史
| 版本 | 日期 | 修改内容 |
|------|------|----------|
| v1.0 | 2026-02-07 | 初始版本 |
| v1.1 | 2026-02-07 | 新增人格化配置、memU/MemOS 方案、记忆召回规则 |
---
*文档版本: v1.1 | 最后更新: 2026-02-07*