# 🤖 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*