700c5e9ab2
4-page layout (Home, Recipes, Settings, Doctor) with sidebar nav and integrated Chat panel powered by OpenClaw agent (--local). - Home: status, agents overview, recommended recipes, recent activity - Recipes: browse, preview diff, apply with params - Settings: model profiles CRUD, chat model selection, provider catalog - Doctor: diagnostics with auto-fix - Chat: OpenClaw agent integration with session persistence, agent selector, read-only advisory context injection - Progressive data loading to avoid UI blocking - API key resolution from OpenClaw agent auth-profiles - Model catalog from openclaw CLI with cache Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
565 lines
22 KiB
Markdown
565 lines
22 KiB
Markdown
# 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 频道专属人设**
|
||
|
||
```yaml
|
||
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 核心接口
|
||
|
||
```typescript
|
||
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
|
||
```yaml
|
||
params:
|
||
- id: guild_id
|
||
type: string
|
||
required: true
|
||
pattern: "^[0-9]+$" # 正则校验
|
||
minLength: 17
|
||
maxLength: 20
|
||
```
|
||
|
||
### 9.2 路径白名单
|
||
```yaml
|
||
# 只允许修改这些路径
|
||
allowedPaths:
|
||
- "channels.*"
|
||
- "agents.defaults.*"
|
||
- "agents.list[*].identity"
|
||
|
||
# 禁止修改
|
||
forbiddenPaths:
|
||
- "gateway.auth.*" # 认证相关
|
||
- "*.token" # 所有 token
|
||
- "*.apiKey" # 所有 API key
|
||
```
|
||
|
||
### 9.3 危险操作标记
|
||
```yaml
|
||
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*
|