摘要

本文详细介绍 OpenClaw 框架下三个思源笔记技能（siyuan-skill、siyuan-notes-skill、siyuan-task-skill）的连接配置、使用方法及实操技巧。涵盖技能安装、环境配置、API 连接、常用命令、错误排查等内容，适合 AI Agent 开发者和思源笔记高级用户参考。

关键词：思源笔记；OpenClaw；AI Agent；技能配置；API 集成；clawhub

⚠️ 脱敏声明：本文所有示例均已脱敏处理，不包含真实 Token、IP 地址、个人路径等敏感信息。

---

1. 引言

1.1 技能安装方式对比

安装方式	命令示例	推荐度	适用场景
clawhub	clawhub install siyuan-skill	⭐⭐⭐⭐⭐	日常使用
skillhub	skillhub install siyuan-skill	⭐⭐⭐⭐	备选方案
手动安装	git clone ...	⭐⭐	开发调试

推荐优先使用 clawhub：最简单常用，自动处理依赖和版本。

1.2 环境要求

• 思源笔记：v2.8.0+
• Node.js：v18+
• Python：v3.7+

---

2. 技能安装

2.1 使用 clawhub 安装（推荐）

# 安装三个思源笔记技能
clawhub install siyuan-skill
clawhub install siyuan-notes-skill
clawhub install siyuan-task-skill

# 查看已安装技能
clawhub list

# 更新技能
clawhub update siyuan-notes-skill

# 卸载技能
clawhub uninstall siyuan-skill

2.2 使用 skillhub 安装

# 搜索技能
skillhub search siyuan

# 安装技能
skillhub install siyuan-skill
skillhub install siyuan-notes-skill
skillhub install siyuan-task-skill

# 查看技能列表
skillhub list

2.3 手动安装（不推荐）

# 克隆仓库
git clone https://github.com/作者/siyuan-skill.git \
  ~/.openclaw/skills/siyuan-skill

# 安装依赖
cd ~/.openclaw/skills/siyuan-skill
npm install

---

3. 前置配置

3.1 获取 API Token

1. 打开思源笔记
2. 进入 设置 → 关于
3. 点击 复制 API Token
4. 保存到安全位置

⚠️ 安全提醒：

• Token 只显示一次
• 不要提交到 Git
• 泄露后立即重置

3.2 验证 API 连接

curl http://127.0.0.1:6806/api/system/version

成功响应：

{
  "code": 0,
  "data": { "version": "2.8.10" }
}

---

4. siyuan-skill 配置

4.1 配置文件位置

# config.json 路径
~/.openclaw/skills/siyuan-skill/config.json
# 复制配置示例
cp config.example.json config.json

4.2 编辑配置

{
  "baseURL": "http://127.0.0.1:6806",
  "token": "你的 API Token",
  "defaultNotebook": "笔记本 ID",
  "permissionMode": "all"
}

4.3 环境变量方式

export SIYUAN_BASE_URL="http://127.0.0.1:6806"
export SIYUAN_TOKEN="你的 API Token"

4.4 常用命令

# 笔记本管理
siyuan nb                     # 获取笔记本列表
siyuan index                  # 索引文档

# 文档操作
siyuan new "文档标题"          # 创建文档
siyuan edit "文档 ID"          # 更新文档

# 搜索查询
siyuan find "关键词"           # 向量搜索

---

5. siyuan-notes-skill 配置

5.1 .env 文件配置（重要）

文件位置：

~/.openclaw/skills/siyuan-notes-skill/.env

配置内容：

# 思源笔记 API 地址配置
SIYUAN_HOST=127.0.0.1
SIYUAN_PORT=6806
SIYUAN_USE_HTTPS=false

# API Token（注意脱敏）
SIYUAN_API_TOKEN=你的 API Token

# 写入保护开关
SIYUAN_ENABLE_WRITE=true

配置说明：

配置项	说明	默认值
SIYUAN_HOST	思源笔记服务器地址	127.0.0.1
SIYUAN_PORT	API 端口	6806
SIYUAN_USE_HTTPS	是否使用 HTTPS	false
SIYUAN_API_TOKEN	API Token	必填
SIYUAN_ENABLE_WRITE	写入保护开关	true

5.2 验证连接

cd ~/.openclaw/skills/siyuan-notes-skill
node index.js check

5.3 编辑策略

⚠️ 选错会导致数据丢失！

操作	正确命令
修改单个块	update-block
删除单个块	delete-block
添加内容	append-block
替换章节	replace-section

5.4 写入安全协议

# 步骤 1：读取文档
node index.js open-doc "文档 ID" readable

# 步骤 2：启用写入
SIYUAN_ENABLE_WRITE=true node index.js append-block "父块 ID" "内容"

---

6. siyuan-task-skill 配置

6.1 config.env 配置

文件位置：

~/.openclaw/skills/siyuan-task-skill/scripts/config.env

配置内容：

SIYUAN_API_URL=http://127.0.0.1:6806
SIYUAN_API_TOKEN=你的 API Token
SIYUAN_NOTEBOOK_NAME=你的笔记本名称

6.2 初始化数据库

cd ~/.openclaw/skills/siyuan-task-skill/scripts
python3 task_ops.py init

6.3 常用命令

# 创建任务
python3 task_ops.py create "任务名称" \
  content="任务内容" \
  importance="高"

# 查询任务
python3 task_ops.py list

# 状态流转
python3 task_ops.py start <row_id>
python3 task_ops.py complete <row_id>

---

7. 常见问题

7.1 连接失败

问题：Connection refused

排查步骤：

# 1. 检查思源笔记是否运行
ps aux | grep siyuan

# 2. 检查端口
netstat -tlnp | grep 6806

# 3. 验证连接
curl http://127.0.0.1:6806/api/system/version

7.2 写入报错

问题：只读模式

原因：未设置 SIYUAN_ENABLE_WRITE=true

解决：

SIYUAN_ENABLE_WRITE=true node index.js append-block "docID" "内容"

7.3 Token 配置错误

检查清单：

• Token 是否正确复制
• .env 文件是否保存
• 是否重启了技能

7.4 版本冲突

问题：Document version mismatch

解决：

node index.js open-doc "文档 ID" readable
# 重新读取后重试

---

8. 安全与脱敏

8.1 必须脱敏的信息

公开文章中禁止出现：

• ❌ 真实的 API Token
• ❌ 服务器真实 IP 地址
• ❌ 个人文件路径（含用户名）
• ❌ 数据库密码
• ❌ 其他敏感配置

8.2 脱敏示例

原始信息	脱敏后
token=abc123xyz	token=你的 API Token
/home/用户名/.openclaw	~/.openclaw
192.168.1.100	127.0.0.1 或 你的服务器 IP

8.3 Git 安全配置

# .gitignore 示例
.env
config.env
*.token
*.secret

---

9. 总结

9.1 安装建议

优先使用 clawhub：

clawhub install siyuan-skill
clawhub install siyuan-notes-skill
clawhub install siyuan-task-skill

9.2 配置要点

技能	配置文件	关键配置项
siyuan-skill	config.json	baseURL, token
siyuan-notes-skill	.env	SIYUAN_HOST, SIYUAN_API_TOKEN
siyuan-task-skill	config.env	SIYUAN_API_URL, SIYUAN_API_TOKEN

9.3 安全提醒

1. ⚠️ 公开文章必须脱敏
2. ⚠️ Token 不要提交到 Git
3. ⚠️ 定期检查配置安全
4. ⚠️ 使用环境变量管理敏感信息

---

参考文献

[1] 思源笔记 API 文档。https://github.com/siyuan-note/siyuan/blob/master/API_zh_CN.md

[2] OpenClaw 官方文档。https://docs.openclaw.ai

[3] ClawHub 技能市场。https://clawhub.ai

[4] Clipboard API 规范。https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API

（完）