Paperless-ngx
Document management via Paperless-ngx REST API.
Configuration
Set environment variables in ~/.clawdbot/clawdbot.json:
CODEBLOCK0
Or configure via the skills entry (allows using apiKey shorthand):
CODEBLOCK1
Get your API token from Paperless web UI: Settings → Users & Groups → [user] → Generate Token.
Quick Reference
| Task | Command |
|---|
| Search documents | INLINECODE2 |
| List recent |
node {baseDir}/scripts/list.mjs [--limit N] |
| Get document |
node {baseDir}/scripts/get.mjs <id> [--content] |
| Upload document |
node {baseDir}/scripts/upload.mjs <file> [--title "..."] [--tags "a,b"] |
| Download PDF |
node {baseDir}/scripts/download.mjs <id> [--output path] |
| List tags |
node {baseDir}/scripts/tags.mjs |
| List types |
node {baseDir}/scripts/types.mjs |
| List correspondents |
node {baseDir}/scripts/correspondents.mjs |
All scripts are in {baseDir}/scripts/.
Common Workflows
Find a document
CODEBLOCK2
Get document details
CODEBLOCK3
Upload a document
CODEBLOCK4
Download a document
CODEBLOCK5
Manage metadata
CODEBLOCK6
Output Format
All scripts output JSON for easy parsing. Use jq for formatting:
CODEBLOCK7
Advanced Usage
For complex queries or bulk operations, see references/api.md for direct API access patterns.
Troubleshooting
"PAPERLESS_URL not set" — Add to ~/.clawdbot/clawdbot.json env section or export in shell.
"401 Unauthorized" — Check PAPERLESS_TOKEN is valid. Regenerate in Paperless UI if needed.
"Connection refused" — Verify Paperless is running and URL is correct (include port).
Upload fails silently — Check Paperless logs; file may be duplicate or unsupported format.
Paperless-ngx
通过 Paperless-ngx REST API 进行文档管理。
配置
在 ~/.clawdbot/clawdbot.json 中设置环境变量：
json
{
env: {
PAPERLESS_URL: http://your-paperless-host:8000,
PAPERLESS_TOKEN: your-api-token
}
}
或者通过技能条目进行配置（允许使用 apiKey 简写）：
json
{
skills: {
entries: {
paperless-ngx: {
env: { PAPERLESS_URL: http://your-paperless-host:8000 },
apiKey: your-api-token
}
}
}
}
从 Paperless Web UI 获取 API 令牌：设置 → 用户与组 → [用户] → 生成令牌。
快速参考
| 任务 | 命令 |
|---|
| 搜索文档 | node {baseDir}/scripts/search.mjs 查询 |
| 列出最近文档 |
node {baseDir}/scripts/list.mjs [--limit N] |
| 获取文档 | node {baseDir}/scripts/get.mjs
[--content] |
| 上传文档 | node {baseDir}/scripts/upload.mjs <文件> [--title ...] [--tags a,b] |
| 下载 PDF | node {baseDir}/scripts/download.mjs [--output 路径] |
| 列出标签 | node {baseDir}/scripts/tags.mjs |
| 列出类型 | node {baseDir}/scripts/types.mjs |
| 列出通信方 | node {baseDir}/scripts/correspondents.mjs |
所有脚本均位于 {baseDir}/scripts/ 目录下。
常见工作流程
查找文档
bash
全文搜索
node {baseDir}/scripts/search.mjs 十二月份电费
按标签筛选
node {baseDir}/scripts/search.mjs --tag 可抵税
按文档类型筛选
node {baseDir}/scripts/search.mjs --type 发票
按通信方筛选
node {baseDir}/scripts/search.mjs --correspondent AGL
组合筛选条件
node {baseDir}/scripts/search.mjs 2025 --tag 未支付 --type 发票
获取文档详情
bash
仅元数据
node {baseDir}/scripts/get.mjs 28
包含 OCR 文本内容
node {baseDir}/scripts/get.mjs 28 --content
完整内容（不截断）
node {baseDir}/scripts/get.mjs 28 --content --full
上传文档
bash
基本上传（标题自动检测）
node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf
带元数据上传
node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf \
--title AGL 2026年1月电费 \
--tags 未支付,公用事业 \
--type 发票 \
--correspondent AGL \
--created 2026-01-15
下载文档
bash
下载到当前目录
node {baseDir}/scripts/download.mjs 28
指定输出路径
node {baseDir}/scripts/download.mjs 28 --output ~/Downloads/document.pdf
获取原始文件（非归档/OCR版本）
node {baseDir}/scripts/download.mjs 28 --original
管理元数据
bash
列出所有标签
node {baseDir}/scripts/tags.mjs
列出文档类型
node {baseDir}/scripts/types.mjs
列出通信方
node {baseDir}/scripts/correspondents.mjs
创建新标签
node {baseDir}/scripts/tags.mjs --create 新标签名称
创建新通信方
node {baseDir}/scripts/correspondents.mjs --create 新公司名称
输出格式
所有脚本输出 JSON 格式，便于解析。使用 jq 进行格式化：
bash
node {baseDir}/scripts/search.mjs 发票 | jq .results[] | {id, title, created}
高级用法
对于复杂查询或批量操作，请参阅 references/api.md 了解直接 API 访问模式。
故障排除
PAPERLESS_URL not set — 将其添加到 ~/.clawdbot/clawdbot.json 的 env 部分，或在 shell 中导出。
401 Unauthorized — 检查 PAPERLESS_TOKEN 是否有效。如有必要，在 Paperless UI 中重新生成。
Connection refused — 确认 Paperless 正在运行且 URL 正确（包含端口）。
上传静默失败 — 检查 Paperless 日志；文件可能重复或格式不受支持。
