OpenClaw + Obsidian 构建个人知识管理系统

本文记录了使用 OpenClaw 管理笔记仓库的完整实践，包括工具配置、部署方案、远程访问和技能开发。通过这套方案，可以实现：

自动化记录 — 通过 Memo 命令快速保存临时想法
结构化整理 — 自动分类到 Inbox/Tasks/Notes/Resources
远程访问 — 配合 ngrok 实现外网访问
技能扩展 — 基于 OpenClaw AgentSkills 规范开发自定义技能

一、工具配置

客户端：Obsidian

跨平台笔记客户端，支持 Markdown
本地存储，数据完全掌控
丰富的插件生态
官网：https://obsidian.md

服务端：fast-note-sync

自托管笔记同步服务
提供 API 接口进行笔记管理
支持多设备同步
GitHub: https://github.com/llm-red-team/fast-note-sync

API 配置

{
  "api": "http://127.0.0.1:9000",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "vault": "图拉国营噄茶馆"
}

目录结构

图拉国营喫茶茶馆/
├── Inbox/          # 随手记录，还没整理的
├── Tasks/          # 待办任务
├── Notes/          # 整理好的笔记
└── Resources/      # 链接和资源收藏

二、fast-note-sync 部署方案

方案一：Docker 部署（推荐）

# 1. 创建数据目录
mkdir -p ~/fast-note-sync/data

# 2. 启动容器
docker run -d \
  --name fast-note-sync \
  -p 9000:9000 \
  -v ~/fast-note-sync/data:/app/data \
  -e JWT_SECRET='your-secret-key' \
  -e VAULT_NAME='图拉国营噄茶馆' \
  llmredteam/fast-note-sync:latest

# 3. 检查状态
docker logs -f fast-note-sync

方案二：源码部署

# 1. 克隆项目
git clone https://github.com/llm-red-team/fast-note-sync.git
cd fast-note-sync

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 JWT_SECRET、VAULT_NAME 等

# 4. 启动服务
npm start
# 或使用 PM2
pm2 start npm --name fast-note-sync -- start

配置文件示例 (.env)

# 服务配置
PORT=9000
HOST=0.0.0.0

# JWT 配置
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=365d

# Vault 配置
VAULT_NAME=图拉国营噄茶馆
VAULT_PATH=/path/to/your/vault

# 安全配置
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

三、远程访问：ngrok 内网穿透

什么是 ngrok？

ngrok 是一款开源的内网穿透工具，通过反向代理在公共端点和本地服务之间建立安全隧道。

核心功能：

将本地/内网服务暴露到公网
自动生成临时公网域名
支持 HTTP/HTTPS/TCP 协议
加密传输，安全可靠

适用场景：

开发调试：让外部访问本地开发环境
远程演示：无需部署服务器即可展示项目
临时 API 服务：快速搭建可公网访问的接口
移动/远程办公：在外访问家中/公司内网服务

ngrok 配合 fast-note-sync 使用

1. 注册 ngrok 账号

访问 https://ngrok.com 注册免费账号，获取 Authtoken。

2. 安装 ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok

# macOS
brew install ngrok/ngrok/ngrok

3. 配置 Authtoken

ngrok config add-authtoken <your-authtoken>

4. 启动隧道

# 方式一：暴露 fast-note-sync 的 9000 端口
ngrok http 9000

# 方式二：指定域名（付费功能）
ngrok http 9000 --domain=your-domain.ngrok.io

启动后会显示：

Forwarding: https://abc123.ngrok.io -> http://localhost:9000

5. 更新 API 配置

将 API 地址改为 ngrok 提供的公网地址：

{
  "api": "https://abc123.ngrok.io",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "vault": "图拉国营噄茶馆"
}

6. ngrok 配置文件示例 (ngrok.yml)

version: 2
authtoken: your-authtoken-here

tunnels:
  fast-note-sync:
    proto: http
    addr: 9000
    domain: your-domain.ngrok.io  # 可选，付费功能

注意事项

免费限制：ngrok 免费版每次重启会变更域名，适合临时使用
稳定性：生产环境建议使用固定域名或自建 frp/nps 等方案
安全性：
- 确保 fast-note-sync 的 JWT_SECRET 足够复杂
- 考虑配置 IP 白名单
- 定期更新 API Token
替代方案：
- frp：开源可自建，适合长期使用
- Cloudflare Tunnel：免费，安全性高
- Tailscale：组网方案，适合私人访问

四、knowledge-pipeline 技能开发

技能概述

名称: knowledge-pipeline
描述: 当用户说 Memo:开头的话，或需要保存信息到笔记库时使用。支持实时记录、知识入库、待办管理。
类型: 工具型技能
核心功能: 将用户的临时记录、待办事项、知识片段自动保存到 Obsidian 笔记库

技能结构

knowledge-pipeline/
├── SKILL.md              # 技能定义文件（必需）
├── scripts/
│   ├── save_memo.py      # 核心脚本：保存笔记到 Obsidian
│   └── quanzhou_trip.md  # 示例笔记（演示输出格式）
└── references/           # 参考资料（可选）

SKILL.md 编写规范

1. Front Matter（必需）

---
name: knowledge-pipeline
description: 当用户说 Memo:开头的话，或需要保存信息到笔记库时使用。支持实时记录、知识入库、待办管理。
---

2. 触发条件

## 触发条件

使用此技能当用户：
1. 发送以 `Memo:` 开头的消息
2. 明确要求保存信息到笔记库
3. 需要创建待办任务或整理笔记

3. 处理流程

## 实时记录规则

当用户说 `Memo:` 开头的消息时：

1. **提取关键信息** — 识别核心内容、标签、分类
2. **选择目录** — 根据内容类型决定放入 Inbox/Tasks/Notes/Resources
3. **写入文件** — 调用 `scripts/save_memo.py` 脚本
4. **回复确认** — 告知用户已保存的位置和摘要

4. 文件命名规范

## 文件命名规范

- **Inbox**: `Inbox/YYYY-MM-DD.md`（按日期归档，同一天多条则追加内容）
- **Tasks**: `Tasks/任务名称.md` 或 `Tasks/YYYY-MM-DD-任务.md`
- **Notes**: `Notes/主题名称.md`
- **Resources**: `Resources/资源名称.md`

核心脚本：save_memo.py

功能：通过 Fast Note Sync Service API 将笔记保存到 Obsidian Vault。

命令行参数：

python scripts/save_memo.py --folder Inbox --content "内容" --title "标题" --append

参数	必需	说明
`--folder`	是	目标文件夹 (Inbox/Tasks/Notes/Resources)
`--content`	是	Markdown 格式的内容
`--title`	否	笔记标题，默认使用日期
`--append`	否	是否追加到现有文件

API 调用

保存笔记

payload = {
    "vault": VAULT,
    "path": path,
    "content": full_content
}

response = requests.post(f"{API_BASE}/api/note", headers=HEADERS, json=payload)

读取现有笔记（追加模式）

payload = {
    "vault": VAULT,
    "path": path
}

response = requests.post(f"{API_BASE}/api/note/get", headers=HEADERS, json=payload)

五、使用示例

示例 1：保存临时记录（Memo）

python scripts/save_memo.py --folder Inbox --content "今天学习了 OpenClaw 技能开发"

输出：

✅ Saved to Inbox/2026-04-01.md

示例 2：创建待办任务

python scripts/save_memo.py --folder Tasks --title "完成技能开发" --content "- [ ] 编写 SKILL.md\n- [ ] 测试 API 调用"

输出：

✅ Saved to Tasks/完成技能开发.md

示例 3：整理知识笔记

python scripts/save_memo.py --folder Notes --title "OpenClaw 技能规范" --content "## 技能结构\n\n技能目录包含..."

示例 4：追加内容到现有笔记

python scripts/save_memo.py --folder Inbox --content "补充内容" --append

示例 5：旅行规划（完整笔记）

# 泉州四日游行程规划 (2026.4.3-4.6)

## 行程概览

- **到达**: 4 月 3 日 16:00 泉州站
- **离开**: 4 月 6 日 16:00 泉州站
- **住宿建议**: 西街附近（鲤城区）

---

## Day 1 - 4 月 3 日 (周五) 到达日

### 下午
- **16:00** 到达泉州站
- **16:30-17:30** 前往酒店办理入住

### 晚上
- **19:00-20:30** 西街晚餐

---

## 实用信息

### 交通
- 泉州站 → 西街：打车约 30 分钟

### 美食推荐
| 类型 | 推荐 |
|------|------|
| 早餐 | 面线糊、花生汤 |
| 正餐 | 姜母鸭、牛排馆 |

---

*Created: 2026-03-18*

六、开发技巧

1. 内容格式化

使用 Markdown 语法
自动添加时间戳
支持追加模式更新

2. 错误处理

if result.get("status"):
    print(f"✅ Saved to {result['data']['path']}")
else:
    print(f"❌ Failed: {result.get('message', 'Unknown error')}")
    exit(1)

3. 路径处理

# 确保标题有.md 后缀
if not title.endswith(".md"):
    title = f"{title}.md"

# 构建完整路径
path = f"{folder}/{title}"

4. 时间戳管理

today = datetime.now().strftime("%Y-%m-%d")
timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

full_content = f"# {title}\n\n{content}\n\n---\n*Created: {timestamp}*\n"

七、扩展方向

可能的改进

标签系统 — 自动提取和添加标签
双向链接 — 识别并创建笔记间的链接
模板系统 — 为不同类型的笔记提供模板
批量导入 — 支持从其他工具导入笔记
智能分类 — 使用 AI 自动判断笔记类型

与其他技能集成

calendar — 将日程自动保存为任务
web-search — 保存搜索结果到 Resources
tavily — 将研究结果整理为 Notes

八、注意事项

API Token 安全 — 不要将 Token 提交到公开仓库
Vault 路径 — 确保 fast-note-sync 有读写权限
编码问题 — 使用 UTF-8 编码，避免中文乱码
网络依赖 — 确保 fast-note-sync 服务运行正常
并发写入 — 同一文件避免同时写入
JWT Token 有效期 — 默认 365 天，过期需重新获取
ngrok 限制 — 免费版域名会变更，生产环境建议自建 frp

九、参考资料

本文整合了 OpenClaw 笔记管理的完整实践