Tools
Research Notes
By OpenClaw plugin for safe Markdown-centered research note file operations.
Install
npm install
npmConfiguration Example
"skills": [
"skills/research-notes"
]README
# Research Notes
Safe Markdown-centered research note tools for OpenClaw.
This plugin exposes a small, restricted file API for research-note workflows. It is intended to let an OpenClaw agent read, write, append, list, and organize notes without giving it generic shell access.
## Purpose
`research-notes` is designed for Markdown-centered research work, especially:
* paper notes
* reading notes
* question lists
* comparison notes
* extraction drafts
* lightweight bibliographic files
* JSON scratch files for structured notes
This plugin is not a general-purpose filesystem or shell replacement.
## Workspace root
All operations are restricted to:
```text
/home/openclaw/research/notes
```
Tool arguments must use relative paths under this root.
Allowed:
```text
papers/2026/example-paper.md
questions/large-n-factorization.md
bibliography/reading-list.bib
scratch/extraction-draft.json
```
Rejected:
```text
/home/openclaw/research/notes/example.md
../example.md
.git/config
.trash/old-note.md
```
The implementation rejects absolute paths, parent-directory escapes, NUL bytes, and blocked internal directories.
## Tools
### `research_read_file`
Read part or all of a supported text file.
Parameters:
* `path`: relative file path
* `start_line`: optional 1-based start line
* `end_line`: optional 1-based inclusive end line
* `max_bytes`: optional byte limit, hard-capped at 512 KiB
Behavior:
* Reads text files only.
* Rejects unsupported extensions.
* Rejects binary-looking files.
* Supports partial line reads.
* Returns whether the read was truncated.
### `research_write_file`
Create or overwrite a supported text file.
Parameters:
* `path`: relative file path
* `content`: text content
* `create_parents`: optional boolean
* `overwrite`: optional boolean, default false
Behavior:
* Creates a new file by default.
* Does not overwrite an existing file unless `overwrite: true` is passed.
* Can create parent directories when `create_parents: true` is passed.
* Uses UTF-8 text.
### `research_append_file`
Append text to a supported text file.
Parameters:
* `path`: relative file path
* `content`: text content to append
* `create_parents`: optional boolean
Behavior:
* Appends UTF-8 text.
* Creates the file if it does not exist.
* Can create parent directories when `create_parents: true` is passed.
### `research_list_dir`
List files and directories under the research workspace.
Parameters:
* `path`: optional relative directory path, defaults to workspace root
* `recursive`: optional boolean, default false
* `max_entries`: optional entry limit, hard-capped at 1000
Behavior:
* Returns path, name, kind, size, and mtime for entries.
* Skips blocked internal directories.
* Supports recursive listing when explicitly requested.
* Returns whether the listing was truncated.
### `research_mkdir`
Create a directory under the research workspace.
Parameters:
* `path`: relative directory path
* `parents`: optional boolean, default false
Behavior:
* Creates a directory.
* Can create parent directories when `parents: true` is passed.
### `research_stat`
Return metadata for a file or directory under the research workspace.
Parameters:
* `path`: relative path
Behavior:
* Returns whether the path exists.
* Returns kind, size, mtime, and extension when applicable.
* Does not fail when the path does not exist; instead returns `exists: false`.
## Allowed file extensions
Initial supported file types are:
```text
.md
.txt
.json
.bib
```
`.tex` is intentionally not enabled in the initial version. The default workflow should use Markdown with embedded TeX equations. LaTeX source editing can be added later if needed.
## Blocked internal directories
The following path segments are blocked:
```text
.git
.trash
```
This is intended to avoid accidental manipulation of internal state or future recovery directories.
## Design choices
### Markdown-first
The plugin is optimized for notes and research scratch work, not general document production.
### Relative paths only
The agent should not be able to address arbitrary host paths. All paths are resolved under `/home/openclaw/research/notes`.
### No hard delete
The initial version does not provide delete or trash tools. If deletion is needed later, prefer a recoverable `research_trash_file` tool rather than hard delete.
### No move tool initially
The initial version does not provide `move_file`. Reorganization has higher risk than reading, appending, or creating notes. A move tool can be added later after the basic workflow has proven stable.
### Explicit overwrite
`research_write_file` does not overwrite existing files unless `overwrite: true` is passed. This prevents accidental note loss.
### Partial reads
`research_read_file` supports line ranges and byte caps so that large notes can be inspected safely.
## Recommended agent workflow
Before writing a new file:
1. Use `research_stat` to check whether the path exists.
2. Use `research_mkdir` if a parent directory is needed.
3. Use `research_write_file` to create the file.
4. Use `research_read_file` to verify important writes.
Before changing an existing file:
1. Use `research_read_file` first.
2. Decide whether the change should be an append or a full rewrite.
3. Prefer `research_append_file` for logs, running notes, and incremental observations.
4. Use `research_write_file` with `overwrite: true` only when replacing the whole file is clearly intended.
When browsing notes:
1. Use `research_list_dir` with `recursive: false` first.
2. Use recursive listing only when needed.
3. Keep `max_entries` modest.
## Skill
This plugin includes the `research-notes` skill.
Expected skill path:
```text
skills/research-notes/SKILL.md
```
Expected manifest entry after `openclaw plugins build`:
```json
"skills": [
"skills/research-notes"
]
```
The skill should appear in Slack with:
```text
/skills
```
Expected entry:
```text
research-notes — manage Markdown-centered research notes
```
## Build and validate
From the plugin directory:
```bash
cd /home/openclaw/.openclaw/local-plugins/research-notes
npm install
npm run build
openclaw plugins build
openclaw plugins validate
```
If the plugin is not installed yet:
```bash
cd /home/openclaw/.openclaw/local-plugins/research-notes
openclaw plugins install -l .
```
After changing tools, skill files, package metadata, or the generated plugin metadata, restart the gateway:
```bash
openclaw gateway restart
```
## Allowlist
In the tested environment, the plugin had to be added to both `tools.alsoAllow` and `tools.sandbox.tools.alsoAllow`.
Example entry:
```json
"research-notes"
```
The tested allowlist included:
```json
[
"group:web",
"group:runtime",
"message",
"arxiv-md",
"belief-kg",
"sandbox_exec",
"sandbox_process",
"research-notes"
]
```
Use `openclaw config get tools` before editing allowlists, and do not remove existing entries accidentally.
## Smoke test
After gateway restart, verify tools from Slack:
```text
/tools
```
Expected connected tools:
```text
research_append_file
research_list_dir
research_mkdir
research_read_file
research_stat
research_write_file
```
Verify skill from Slack:
```text
/skills
```
Expected skill:
```text
research-notes — manage Markdown-centered research notes
```
Recommended agent test prompt:
```text
Use the research-notes skill. Create a small test note at test/hello.md, read it back, then report only whether the tool workflow succeeded. Do not use shell commands.
```
Expected result:
```text
/home/openclaw/research/notes/test/hello.md
```
is created and can be read back through `research_read_file`.
## Skill packaging note
When adding a skill to a plugin, ensure `package.json` includes `skills` in `files`:
```json
"files": [
"dist",
"openclaw.plugin.json",
"README.md",
"skills"
]
```
Then run:
```bash
openclaw plugins build
```
and confirm that `openclaw.plugin.json` contains:
```json
"skills": [
"skills/research-notes"
]
```
## SKILL.md frontmatter warning
`SKILL.md` must start with valid YAML frontmatter.
Correct:
```markdown
---
name: research-notes
description: "Use when reading, writing, appending, listing, or creating Markdown-centered research notes in the restricted research workspace. Prefer this over shell commands for note workflows."
---
# Research Notes
```
Incorrect:
```text
---
name: research-notes
description: "..."
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
```
The incorrect form was observed when Markdown was pasted from a rendered view. In that state, `openclaw plugins build` did not generate the manifest `skills` entry.
If `/tools` shows the plugin tools but `/skills` does not show the skill, check the frontmatter first:
```bash
cd /home/openclaw/.openclaw/local-plugins/research-notes
sed -n '1,12p' skills/research-notes/SKILL.md
```
The first lines must look like:
```text
---
name: research-notes
description: "..."
---
```
Do not directly edit `openclaw.plugin.json` to add `skills`; it is generated metadata and `openclaw plugins validate` may report it as stale.
## Current status
Implemented and tested:
* `research_read_file`
* `research_write_file`
* `research_append_file`
* `research_list_dir`
* `research_mkdir`
* `research_stat`
* `research-notes` skill
* Slack `/tools` visibility
* Slack `/skills` visibility
* minimal write/read smoke test
Not implemented initially:
* file move
* recoverable trash
* hard delete
* `.tex` editing support
* arbitrary host filesystem access
tools
Comments
Sign in to leave a comment