An AI-agent skill for querying and managing Joplin notes, notebooks, and tags locally or remotely via the Clipper Server.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install joplin-api-china
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install joplin-api-china using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Joplin Data API Skill?
The Joplin Data API Skill allows your AI coding agent to seamlessly connect to your local or remote Joplin notebook via the Clipper Server (Web Clipper API). This powerful addition to Openclaw Skills enables automated read, write, update, and search operations over your personal database, transforming Joplin into an active, AI-accessible knowledge base.
Built with strict security guardrails, the skill ensures that write and delete actions are never executed silently, giving you complete oversight of your knowledge base. It supports both high-speed local connections and remote operations via SSH tunnels, allowing developers to manage knowledge effortlessly across multiple systems.
Joplin Data API Skill Use Cases
- Search and retrieve notes, notebooks, and tags containing specific keywords or topics directly via your AI agent.
- Create new Markdown notes dynamically inside designated notebooks to log development updates, code snippets, or system outputs.
- Update existing notes systematically to maintain live documentation and personal wikis without leaving your terminal.
- Map out complex personal knowledge hierarchies by rendering notebook structures as interactive nested trees.
How Joplin Data API Skill Works
- Trigger Action: The AI agent invokes the skill when a query matches patterns like "Search Joplin" or "Create note in Joplin".
- Connection Routing: The tool reads environment configuration to determine whether to connect directly to the local Clipper Server (localhost:41184) or route requests through an SSH tunnel to a remote host.
- Query Execution: Utilizing standard scripts (joplin.sh or joplin.py), the skill queries the Joplin REST API, retrieving objects (notes, notebooks, or tags) mapped through parent_id parameters.
- Security Check: For reading operations (GET), data is fetched instantly. For high-impact operations (POST, PUT, DELETE), the skill halts execution, displays the payload preview, and prompts the user for explicit confirmation.
- Response Delivery: The formatted JSON output or friendly preview is sent back to the agent or interface for further reasoning.
Joplin Data API Skill Setup
Initial Setup
Navigate to the skill directory, copy the example environment file, and configure your credentials:
cd ~/.openclaw/skills/joplin-api
cp .env.example .env
nano .env
Get Your API Token
- Open your Joplin desktop application.
- Go to Tools / Preferences (or Options / Preferences) -> Web Clipper.
- Copy the Access password (Token).
- Paste it into your
.envfile asapi_token=your_copied_token.
Configure Environment Variables
Edit the .env configuration:
# Token from Joplin Web Clipper settings
api_token=xxx
# SSH Alias for remote hosting (leave blank for localhost)
joplin_host=
# Default Clipper port used for local execution
base_url=http://localhost:41184
Test the Connection
Run the built-in ping test script to verify communication with the Clipper Server:
# For Linux / macOS (Recommended)
bash scripts/joplin.sh ping
# For Windows or systems without Bash
python scripts/joplin.py ping
Joplin Data API Skill Data Schema & Taxonomy
Joplin Data Model & Hierarchy
Joplin stores and structures documents as a hierarchical graph using specific parent-child definitions:
| Object | Key Fields | Description |
|---|---|---|
| Folder (Notebook) | id, title, parent_id |
Represents a notebook category. Supports infinite nested hierarchies via parent IDs pointing to other folder IDs. |
| Note (Content) | id, title, body, parent_id |
Contains the Markdown content (body). It is assigned strictly to a single folder via its parent_id. |
| Tag (Metadata) | id, title |
Global keywords mapped across notes, ignoring folder hierarchy restrictions. |
| Resource (Asset) | id, title, mime_type |
Media assets, files, or attachments linked directly within notes. |
Operational Iron Rules for Data Handling
- Read Optimization: Search scripts perform lightweight fetching (
fields=id,title) to keep operations fast, retrieving the heavier note body content only when a specific note is selected. - Trash Bin Protection: Note deletions default to soft-deletes (sent to the Joplin Trash Bin) unless the
--permanentflag is specifically authorized.
Joplin Data API Skill Advanced Features
- Dual Connection Architecture: Supports ultra-fast local Direct REST calls and Secure Remote SSH tunneling modes.
- Multi-Environment Standard Scripting: Includes dual implementations in pure Bash (
joplin.sh) for performance and Python 3 (joplin.py) with zero external dependencies for cross-platform robustness. - Interactive Previews: Leverages human-in-the-loop protection routines requiring deliberate console confirmations for mutations.
- Interactive Tree Visualizer: Built-in tree command renders an organizational map of all notebooks instantly to help coordinate content storage directories.
SKILL.md
Loading
Related Openclaw Skills
AI Nutritionist
An AI-powered multi-dimensional nutrition consultant that generates personalized dietary plans, chronic disease nutrition guides, TCM constitution diet therapy, and interactive HTML reports.
Alibaba Cloud Network Health Inspection
A production-grade diagnostic automation tool that securely evaluates 11 Alibaba Cloud network products using read-only API calls to generate rich reports and visualizations.
Book to Skills
An automated intelligent tool that converts electronic books into structured knowledge bases and actionable AI agent skill packages.
Apple Mail Channel Setup & Configuration
An Apple Mail channel plugin for OpenClaw and Hermes that enables AI agents to read, process, and automatically reply to email threads on macOS via AppleScript.
E-Store Skill
A powerful integration skill enabling AI agents to search, browse, download, and install skills, MCP servers, and comprehensive agent solutions directly from the e-store marketplace.
AI Test Engineer
An expert AI testing assistant transforming junior engineers into masters by implementing a 7-phase, 48-module full-lifecycle QA framework.
Featured*
