clawpal/design.md

ClawPal Design Document

OpenClaw 配置助手 — 让普通用户也能玩转高级配置

1. 产品定位

问题

• OpenClaw 配置功能强大但复杂
• 官方 Web UI 是"配置项罗列"，用户看晕
• 用户让 Agent 自己配置，经常出错
• 配置出错时 Gateway 起不来，陷入死循环

解决方案

场景驱动的配置助手

• 不是"列出所有配置项"，而是"你想实现什么场景？"
• 用户选场景 → 填几个参数 → 一键应用
• 独立运行，不依赖 Gateway（配置坏了也能修）

核心价值

1. 降低门槛 — 普通用户也能用上高级功能
2. 最佳实践 — 社区沉淀的配置方案，一键安装
3. 急救工具 — 配置出问题时的救命稻草
4. 版本控制 — 改坏了一键回滚

2. 产品架构

┌─────────────────────────────────────────────────────────┐
│                    clawpal.dev (官网)                    │
│                                                         │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│   │ Recipe  │  │ Recipe  │  │ Recipe  │  │ Recipe  │   │
│   │  Card   │  │  Card   │  │  Card   │  │  Card   │   │
│   └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘   │
│        │            │            │            │         │
│        └────────────┴─────┬──────┴────────────┘         │
│                           │                             │
│                    [一键安装按钮]                         │
│                           │                             │
└───────────────────────────┼─────────────────────────────┘
                            │
                            │ clawpal://install/recipe-id
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 ClawPal App (本地)                       │
│                                                         │
│   ┌──────────────────────────────────────────────────┐  │
│   │                   首页                            │  │
│   │  ┌─────────┐  当前配置健康状态: ✅ 正常           │  │
│   │  │  状态   │  OpenClaw 版本: 2026.2.13           │  │
│   │  │  卡片   │  活跃 Agents: 4                     │  │
│   │  └─────────┘                                     │  │
│   └──────────────────────────────────────────────────┘  │
│                                                         │
│   ┌──────────────────────────────────────────────────┐  │
│   │                  场景库                           │  │
│   │  ┌─────────┐  ┌─────────┐  ┌─────────┐          │  │
│   │  │ Discord │  │ Telegram│  │  模型   │          │  │
│   │  │ 人设    │  │ 配置    │  │  切换   │          │  │
│   │  └─────────┘  └─────────┘  └─────────┘          │  │
│   └──────────────────────────────────────────────────┘  │
│                                                         │
│   ┌──────────────────────────────────────────────────┐  │
│   │                 历史记录                          │  │
│   │  ● 2026-02-15 21:30 应用了 "Discord 人设"        │  │
│   │  ● 2026-02-15 20:00 手动编辑                     │  │
│   │  ● 2026-02-14 15:00 应用了 "性能优化"            │  │
│   │                              [回滚到此版本]        │  │
│   └──────────────────────────────────────────────────┘  │
│                                                         │
└──────────────────────────┬──────────────────────────────┘
                           │
                           │ 直接读写（不依赖 Gateway）
                           ▼
                 ~/.openclaw/openclaw.json

3. 核心功能

3.1 场景库 (Recipes)

每个 Recipe 是一个"配置方案"，包含：

• 标题、描述、标签
• 需要用户填的参数
• 配置补丁模板

示例 Recipe：Discord 频道专属人设

id: discord-channel-persona
name: "Discord 频道专属人设"
description: "给特定 Discord 频道注入专属 system prompt，让 Agent 在不同频道表现不同"
author: "zhixian"
version: "1.0.0"
tags: ["discord", "persona", "beginner"]
difficulty: "easy"

# 用户需要填的参数
params:
  - id: guild_id
    label: "服务器 ID"
    type: string
    placeholder: "右键服务器 → 复制服务器 ID"
    
  - id: channel_id
    label: "频道 ID"
    type: string
    placeholder: "右键频道 → 复制频道 ID"
    
  - id: persona
    label: "人设描述"
    type: textarea
    placeholder: "在这个频道里，你是一个..."

# 配置补丁（JSON Merge Patch 格式）
patch: |
  {
    "channels": {
      "discord": {
        "guilds": {
          "{{guild_id}}": {
            "channels": {
              "{{channel_id}}": {
                "systemPrompt": "{{persona}}"
              }
            }
          }
        }
      }
    }
  }

3.2 引导式安装流程

[选择场景] → [填写参数] → [预览变更] → [确认应用] → [完成]
     │            │            │            │
     │            │            │            └── 自动备份当前配置
     │            │            └── Diff 视图，清晰展示改了什么
     │            └── 表单 + 实时校验
     └── 卡片式浏览，带搜索/筛选

3.3 版本控制 & 回滚

~/.openclaw/
├── openclaw.json              # 当前配置
└── .clawpal/
    ├── history/
    │   ├── 2026-02-15T21-30-00_discord-persona.json
    │   ├── 2026-02-15T20-00-00_manual-edit.json
    │   └── 2026-02-14T15-00-00_performance-tuning.json
    └── metadata.json          # 历史记录元数据

回滚流程

1. 选择历史版本
2. 展示 Diff（当前 vs 目标版本）
3. 确认回滚
4. 当前版本也存入历史（防止误操作）

3.4 配置诊断 (Doctor)

当 Gateway 起不来时，ClawPal 可以独立运行诊断：

检查项

• JSON 语法是否正确
• 必填字段是否存在
• 字段类型是否正确
• 端口是否被占用
• 文件权限是否正确
• Token/密钥格式是否正确

自动修复

• 语法错误：尝试修复常见问题（尾逗号、引号）
• 缺失字段：填充默认值
• 格式错误：自动转换

4. 官网设计

4.1 首页

┌─────────────────────────────────────────────────────────┐
│                      ClawPal                            │
│         让 OpenClaw 配置变得简单                         │
│                                                         │
│              [下载 App]  [浏览 Recipes]                  │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │            热门 Recipes                          │   │
│  │  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐   │   │
│  │  │ 🎭  │  │ ⚡  │  │ 🔔  │  │ 🤖  │  │ 📝  │   │   │
│  │  │人设 │  │性能 │  │提醒 │  │模型 │  │日记 │   │   │
│  │  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘   │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │            提交你的 Recipe                       │   │
│  │  分享你的最佳实践，帮助更多人                      │   │
│  │                    [提交]                        │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

4.2 Recipe 详情页

┌─────────────────────────────────────────────────────────┐
│  ← 返回                                                 │
│                                                         │
│  Discord 频道专属人设                           v1.0.0  │
│  by zhixian                                             │
│                                                         │
│  ⬇️ 1,234 安装   ⭐ 4.8 (56 评价)                       │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  给特定 Discord 频道注入专属 system prompt，     │   │
│  │  让 Agent 在不同频道表现不同。                   │   │
│  │                                                  │   │
│  │  适用场景：                                      │   │
│  │  • 工作频道严肃，闲聊频道轻松                    │   │
│  │  • 不同频道不同语言                              │   │
│  │  • 特定频道禁用某些功能                          │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  需要填写的参数：                                       │
│  • 服务器 ID                                           │
│  • 频道 ID                                             │
│  • 人设描述                                            │
│                                                         │
│              [在 ClawPal 中安装]                        │
│                                                         │
│  ─────────────────────────────────────────────────     │
│                                                         │
│  配置预览                                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │ channels:                                        │   │
│  │   discord:                                       │   │
│  │     guilds:                                      │   │
│  │       "{{guild_id}}":                           │   │
│  │         channels:                                │   │
│  │           "{{channel_id}}":                     │   │
│  │             systemPrompt: "{{persona}}"         │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

4.3 Deep Link 协议

clawpal://install/{recipe-id}
clawpal://install/{recipe-id}?source=web&version=1.0.0

App 收到 deep link 后：

1. 下载 recipe 元数据
2. 打开安装向导
3. 引导用户填写参数
4. 应用配置

5. 技术栈

5.1 本地 App

ClawPal App (Tauri)
├── src-tauri/           # Rust 后端（轻量，主要用 Tauri API）
│   ├── src/
│   │   └── main.rs      # 入口 + 少量原生逻辑
│   └── tauri.conf.json  # Tauri 配置
│
└── src/                 # Web 前端
    ├── App.tsx
    ├── pages/
    │   ├── Home.tsx         # 首页 + 状态
    │   ├── Recipes.tsx      # 场景库
    │   ├── Install.tsx      # 安装向导
    │   ├── History.tsx      # 历史记录
    │   └── Doctor.tsx       # 诊断修复
    ├── components/
    │   ├── RecipeCard.tsx
    │   ├── ParamForm.tsx
    │   ├── DiffViewer.tsx
    │   └── ...
    └── lib/
        ├── config.ts        # 配置读写（用 Tauri fs API）
        ├── recipe.ts        # Recipe 解析/应用
        ├── backup.ts        # 版本控制
        └── doctor.ts        # 诊断逻辑

5.2 技术选型

组件	选型	理由
App 框架	Tauri 2.0	轻量(5-10MB)，JS 为主
前端框架	React + TypeScript	生态成熟
UI 组件	shadcn/ui	好看，可定制
状态管理	React Context + useReducer	先用原生，后续再引入 Zustand
配置解析	json5	支持注释
Diff 展示	monaco-editor diff	可控性强，定制成本低

5.3 RecipeEngine 核心接口

interface RecipeEngine {
  // 校验 recipe 定义 + 用户参数
  validate(recipe: Recipe, params: Record<string, unknown>): ValidationResult;
  
  // 预览变更（不实际修改）
  preview(recipe: Recipe, params: Record<string, unknown>): PreviewResult;
  
  // 应用配置（自动备份）
  apply(recipe: Recipe, params: Record<string, unknown>): ApplyResult;
  
  // 回滚到指定快照
  rollback(snapshotId: string): RollbackResult;
  
  // 从损坏状态恢复
  recover(): RecoverResult;
}

interface PreviewResult {
  diff: string;                    // 配置 Diff
  impactLevel: 'low' | 'medium' | 'high';  // 影响级别
  affectedPaths: string[];         // 受影响的配置路径
  canRollback: boolean;            // 是否可回滚
  overwritesExisting: boolean;     // 是否覆盖现有配置
  warnings: string[];              // 警告信息
}

5.3 官网

组件	选型	理由
框架	Next.js	SSR/SSG，SEO 友好
部署	Vercel / Cloudflare Pages	免费，CDN
数据库	Supabase / PlanetScale	Recipe 存储
认证	GitHub OAuth	用户提交 recipe

6. MVP 范围（精简版）

先做 3 个高价值核心功能，离线可用，快速验证

MVP 核心功能

1. 安装向导

• 参数校验（schema 验证）
• 变更预览（Diff 视图）
• 应用配置
• 自动备份

2. 版本快照与回滚

• 每次修改前自动快照
• 历史记录列表
• 一键回滚
• 回滚前预览 Diff

3. 配置诊断

• JSON 语法检查
• 必填字段验证
• 端口占用检测
• 文件权限检查
• 一键修复 + 显示变更原因

MVP 不做的事

• ❌ 官网
• ❌ 用户系统 / OAuth
• ❌ 评分/评论体系
• ❌ 在线 Recipe 仓库

后续阶段

• Phase 2: 官网 + Recipe 在线分发
• Phase 3: 社区功能（评分、评论、用户提交）

7. 初始 Recipe 列表

MVP 内置的 Recipes：

1. Discord 频道专属人设 — 不同频道不同性格
2. Telegram 群组配置 — 群聊 mention 规则
3. 定时任务配置 — Heartbeat + Cron 基础设置
4. 模型切换 — 快速切换默认模型
5. 性能优化 — contextPruning + compaction 最佳实践

---

8. 风险点 & 注意事项

8.1 Schema 版本兼容

• OpenClaw 配置 schema 会随版本变化
• 需要锁定版本兼容层（v1/v2 schema migration）
• Recipe 需标注兼容的 OpenClaw 版本范围

8.2 安全性

• 深度链接可信源校验：防止恶意 recipe 写入本地配置
• 敏感路径白名单：限制 recipe 可修改的配置路径
• 危险操作提醒：涉及 token、密钥、敏感路径时 must-have 确认

8.3 平台兼容

• Tauri 2.0 在 Windows/macOS 路径权限表现有差异
• 需要测试不同平台的文件读写行为
• 路径处理使用 Tauri 的跨平台 API

8.4 WSL2 支持（Windows 重点）

很多 Windows 用户通过 WSL2 安装 OpenClaw，配置文件在 Linux 文件系统里。

检测逻辑

1. 检查 Windows 原生路径 %USERPROFILE%\.openclaw\
2. 如果不存在，扫描 \\wsl$\*\home\*\.openclaw\
3. 找到多个时让用户选择

路径映射

WSL2 路径:     /home/user/.openclaw/openclaw.json
Windows 访问:  \\wsl$\Ubuntu\home\user\.openclaw\openclaw.json

UI 处理

• 首次启动检测安装方式
• 设置页可手动切换/指定路径
• 显示当前使用的路径来源（Windows / WSL2-Ubuntu / 自定义）

8.5 JSON5 风格保持

• 用户手写的注释和缩进不能被破坏
• 写回时需保持原有格式风格
• 考虑使用 AST 级别的修改而非 stringify

---

9. Recipe 校验规则

9.1 参数 Schema

params:
  - id: guild_id
    type: string
    required: true
    pattern: "^[0-9]+$"           # 正则校验
    minLength: 17
    maxLength: 20

9.2 路径白名单

# 只允许修改这些路径
allowedPaths:
  - "channels.*"
  - "agents.defaults.*"
  - "agents.list[*].identity"
  
# 禁止修改
forbiddenPaths:
  - "gateway.auth.*"              # 认证相关
  - "*.token"                     # 所有 token
  - "*.apiKey"                    # 所有 API key

9.3 危险操作标记

dangerousOperations:
  - path: "gateway.port"
    reason: "修改端口可能导致连接中断"
    requireConfirm: true
  - path: "channels.*.enabled"
    reason: "禁用频道会影响消息收发"
    requireConfirm: true

---

10. 体验细节

10.1 影响级别展示

安装按钮显示"预估影响级别"：

级别	条件	展示
🟢 低	只添加新配置，不修改现有	"添加新配置"
🟡 中	修改现有配置，可回滚	"修改配置（可回滚）"
🔴 高	涉及敏感路径或大范围修改	"重要变更（请仔细检查）"

10.2 可回滚提示

每个 Recipe 显示：

• ✅ 可回滚 / ⚠️ 部分可回滚 / ❌ 不可回滚
• 是否会覆盖现有配置（高亮显示冲突项）

10.3 历史记录增强

• 关键词筛选
• 仅显示可回滚节点
• 按 Recipe 类型分组

10.4 Doctor 一键修复

发现 2 个问题：

1. ❌ JSON 语法错误（第 42 行）
   → 多余的逗号
   [一键修复] 删除第 42 行末尾的逗号

2. ❌ 必填字段缺失
   → agents.defaults.workspace 未设置
   [一键修复] 设置为默认值 "~/.openclaw/workspace"

[全部修复] [仅修复语法] [查看变更详情]

---

11. 落地步骤（推荐顺序）

Step 1: RecipeEngine 核心

1. 定义 RecipeEngine 接口
2. 实现 validate → preview → apply → rollback → recover
3. 编写单元测试

Step 2: 端到端流程验证

1. 实现一个真实 Recipe（Discord 人设）
2. 完整走通：选择 → 填参数 → 预览 → 应用 → 回滚
3. 验证 JSON5 风格保持

Step 3: 损坏恢复演练

1. 模拟配置损坏场景
2. 测试 Doctor 诊断流程
3. 验证一键修复功能

Step 4: 扩展 & 发布

1. 添加 2-3 个 Recipe
2. 完善 UI 细节
3. 打包发布（macOS / Windows / Linux）

---

附录

A. 隐藏但有用的配置能力

这些是 OpenClaw 支持但用户不一定知道的功能：

功能	配置路径	说明
Channel 级 systemPrompt	channels.*.guilds.*.channels.*.systemPrompt	频道专属人设
Context Pruning	agents.defaults.contextPruning	上下文裁剪策略
Compaction	agents.defaults.compaction	Session 压缩
Bindings	bindings[]	按条件路由到不同 Agent
Media Audio	tools.media.audio	语音转录配置
Memory Search	agents.defaults.memorySearch	记忆搜索配置

B. 文件路径

文件	路径
OpenClaw 配置	~/.openclaw/openclaw.json
ClawPal 历史	~/.openclaw/.clawpal/history/
ClawPal 元数据	~/.openclaw/.clawpal/metadata.json

---

Last updated: 2026-02-15