Joplin API

Joplin API Skill

通过 Joplin Data API 管理笔记、笔记本和标签。支持自定义主机地址和端口，适用于本地、Docker 或远程部署的 Joplin。

🔐 环境变量

必需配置: JOPLIN_TOKEN (API Token)

可选配置: JOPLIN_HOST (默认：localhost), JOPLIN_PORT (默认：41184)

配置方法

方法 1: 使用配置模板

cd /root/.openclaw/workspace/skills/joplin-api
cp CONFIG.example .env
# 编辑 .env 填入你的 API Token

方法 2: 手动创建 .env 文件

# .env 文件内容
JOPLIN_HOST=localhost
JOPLIN_PORT=41184
JOPLIN_TOKEN=your_api_token_here

方法 3: 使用系统环境变量

export JOPLIN_TOKEN="your_token"
export JOPLIN_HOST="192.168.1.100"  # 可选
export JOPLIN_PORT="41184"          # 可选

🎯 功能特性

基础操作

• ✅ 连接测试 - 验证 API 连接状态
• ✅ 统计信息 - 查看笔记本、笔记、标签数量
• ✅ 最近笔记 - 查看最近更新的笔记

笔记管理

• ✅ 列出笔记 - 查看所有笔记或指定笔记本的笔记
• ✅ 获取笔记 - 查看笔记详情和内容
• ✅ 创建笔记 - 新建笔记到指定笔记本
• ✅ 更新笔记 - 修改笔记标题或内容
• ✅ 删除笔记 - 删除单条笔记
• ✅ 搜索笔记 - 按关键词搜索笔记
• ✅ 移动笔记 - 移动笔记到其他笔记本
• ✅ 导出笔记 - 导出为 Markdown 或 JSON

笔记本管理

• ✅ 列出笔记本 - 查看所有笔记本
• ✅ 创建笔记本 - 新建笔记本或子笔记本
• ✅ 重命名笔记本 - 修改笔记本名称
• ✅ 删除笔记本 - 删除空笔记本

标签管理

• ✅ 列出标签 - 查看所有标签
• ✅ 查看笔记标签 - 查看某条笔记的标签
• ✅ 添加标签 - 为笔记添加标签（自动创建新标签）
• ✅ 移除标签 - 从笔记移除标签

批量操作

• ✅ 批量移动 - 移动整个笔记本的笔记
• ✅ 批量导入 - 导入 Markdown 文件或整个目录
• ✅ 批量导出 - 导出所有笔记到本地

🚀 快速开始

1. 安装依赖

pip install requests python-dotenv

2. 配置连接

cd /root/.openclaw/workspace/skills/joplin-api
cp CONFIG.example .env

编辑 .env 文件:

# Joplin Data API 配置
JOPLIN_HOST=localhost          # 主机地址（IP、域名均可）
JOPLIN_PORT=41184              # API 端口
JOPLIN_TOKEN=your_api_token    # 从 Joplin 获取的 API Token

3. 获取 API Token

1. 打开 Joplin 桌面版
2. 进入 工具 → 选项 → Web Clipper
3. 勾选 启用 Web Clipper 服务
4. 复制 "API Token" 填入 .env

4. 测试连接

python3 scripts/joplin_ping.py

看到 ✅ 连接成功! 即表示配置正确。

📖 使用指南

统一入口（推荐）

使用 joplin 统一命令:

python3 scripts/joplin.py <command> [args]

各命令详解

🔍 查询类

# 测试连接
python3 scripts/joplin.py ping

# 查看统计
python3 scripts/joplin.py stats

# 最近笔记
python3 scripts/joplin.py recent --limit 5

# 列出所有笔记本
python3 scripts/joplin.py folders list

# 列出所有笔记
python3 scripts/joplin.py list --type notes

# 列出所有标签
python3 scripts/joplin.py tags list

# 查看某笔记本的笔记
python3 scripts/joplin.py folder-notes --folder "工作"

# 搜索笔记
python3 scripts/joplin.py search "会议纪要"

# 查看笔记详情
python3 scripts/joplin.py get --id <note_id>

# 查看笔记的标签
python3 scripts/joplin.py tags note-tags --note-id <note_id>

✏️ 编辑类

# 创建笔记
python3 scripts/joplin.py create --title "待办" --body "内容..."
python3 scripts/joplin.py create --title "笔记" --folder "工作"

# 更新笔记
python3 scripts/joplin.py update --id <note_id> --title "新标题"
python3 scripts/joplin.py update --id <note_id> --body "新内容"

# 移动笔记
python3 scripts/joplin.py move --note-id <note_id> --to-folder "归档"

# 添加标签
python3 scripts/joplin.py tags add --note-id <note_id> --tag "重要"

# 移除标签
python3 scripts/joplin.py tags remove --note-id <note_id> --tag-id <tag_id>

# 删除笔记
python3 scripts/joplin.py delete --id <note_id> --type notes

# 创建笔记本
python3 scripts/joplin.py folders create --name "新项目"

# 重命名笔记本
python3 scripts/joplin.py folders rename --id <folder_id> --name "新名称"

# 删除笔记本
python3 scripts/joplin.py folders delete --id <folder_id>

📦 导入导出

# 导出单条笔记
python3 scripts/joplin.py export --note-id <note_id> -o output.md

# 导出所有笔记
python3 scripts/joplin.py export --all -o ./backup

# 导入单个文件
python3 scripts/joplin.py import note.md --folder "导入"

# 导入整个目录
python3 scripts/joplin.py import ./notes --folder "批量导入"

🔄 批量操作

# 批量移动整个笔记本
python3 scripts/joplin.py move --batch-from "旧文件夹" --batch-to "新文件夹"

🔧 配置示例

本地 Joplin（默认）

JOPLIN_HOST=localhost
JOPLIN_PORT=41184

Docker 部署

JOPLIN_HOST=192.168.1.100
JOPLIN_PORT=41184

远程服务器 + 反向代理

JOPLIN_HOST=joplin.example.com
JOPLIN_PORT=443

📝 使用场景

场景 1: 快速记录

python3 scripts/joplin.py create --title "临时想法" --body "..." --folder "Inbox"

场景 2: 整理笔记

# 查看 Inbox 有哪些笔记
python3 scripts/joplin.py folder-notes --folder "Inbox"

# 移动到对应分类
python3 scripts/joplin.py move --note-id <id> --to-folder "工作"

场景 3: 备份

# 每周导出所有笔记
python3 scripts/joplin.py export --all -o ~/joplin-backup/$(date +%Y%m%d)

场景 4: 知识整理

# 搜索相关笔记
python3 scripts/joplin.py search "机器学习"

# 批量添加标签
for id in $(...); do
  python3 scripts/joplin.py tags add --note-id $id --tag "AI"
done

⚠️ 注意事项

1. Web Clipper 必须启用 - Data API 依赖此服务
2. 端口防火墙 - 远程访问需开放 41184 端口
3. API Token 安全 - 不要泄露 Token，建议用 .env 文件
4. 备份 - 删除操作不可恢复，建议定期导出

🐛 故障排查

无法连接:

• 检查 Joplin 是否运行
• 确认 Web Clipper 已启用
• 验证主机地址和端口

认证失败:

• 检查 API Token 是否正确
• Token 可在 Joplin 设置中重新生成

权限问题:

• 确保脚本可执行：chmod +x scripts/*.py