joplin-api

name	joplin-api
description	Manage Joplin notes, notebooks, and tags via Joplin Data API. Use when the user needs to create, read, update, delete, search, or organize Joplin notes programmatically. Supports custom host/port for local, Docker, or remote Joplin deployments.
allowed-tools	Bash(joplin-api:*)
homepage	https://joplinapp.org/help/api/references/rest_api/
metadata	{"openclaw":{"requires":{"bins":["python3"]},"install":[{"id":"deps","kind":"pip","package":"requests python-dotenv","label":"Install Python dependencies"}],"env":[{"name":"JOPLIN_HOST","required":false,"default":"localhost","description":"Joplin Data API host"},{"name":"JOPLIN_PORT","required":false,"default":"41184","description":"Joplin Data API port"},{"name":"JOPLIN_TOKEN","required":true,"description":"API Token from Joplin Web Clipper settings"}]}}

Joplin API Skill

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

🔐 环境变量

必需配置: JOPLIN_TOKEN (API Token)

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

变量名	必需	默认值	说明
JOPLIN_HOST	可选	localhost	Joplin 主机地址（IP 或域名）
JOPLIN_PORT	可选	41184	Joplin Data API 端口
JOPLIN_TOKEN	必需	-	从 Joplin Web Clipper 获取的 API Token

配置方法

方法 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