---

name: paperless-ngx description: Manage Paperless-NGX document management system via REST API. Upload, search, tag, and organize documents using natural language commands. Ideal for digital document archives, receipt management, and PDF organization workflows. metadata: { "openclaw": { "emoji": "📄", "requires": { "bins": ["python3", "curl", "jq"], "env": ["PAPERLESS_URL", "PAPERLESS_TOKEN"] }, "primaryEnv": "PAPERLESS_TOKEN", "install": [ { "id": "python-brew", "kind": "brew", "formula": "python", "bins": ["python3"], "label": "Install Python (brew)", }, { "id": "curl-brew", "kind": "brew", "formula": "curl", "bins": ["curl"], "label": "Install curl (brew)", }, { "id": "jq-brew", "kind": "brew", "formula": "jq", "bins": ["jq"], "label": "Install jq (brew)", }, ], }, }

Paperless-NGX Manager

智能文档管理助手，通过自然语言指令管理 Paperless-NGX 文档系统。

快速开始

1. 环境配置

环境变量配置

# 设置 Paperless-NGX 实例地址
export PAPERLESS_URL="http://your-paperless-url:8000"

# 设置 API Token（从 Paperless-NGX 设置中获取）
export PAPERLESS_TOKEN="your-api-token-here"

通用配置方法

# 设置 Paperless-NGX 实例地址
export PAPERLESS_URL="http://your-paperless-url:8000"

# 设置 API Token（从 Paperless-NGX 设置中获取）
export PAPERLESS_TOKEN="your-api-token-here"

# 可选：设置默认文档类型和标签
export PAPERLESS_DEFAULT_TYPE="Document"
export PAPERLESS_DEFAULT_TAGS="inbox,unsorted"

2. 基础使用

# 上传文档
python3 scripts/upload.py ~/Downloads/invoice.pdf --title "2024-01 发票" --tag "发票"

# 搜索文档
python3 scripts/search.py --query "发票"

# 查看文档详情
python3 scripts/documents.py --get 123

# 更新文档标签
python3 scripts/documents.py --update 123 --tag "已报销"

核心命令

📤 上传文档

# 基础上传
python3 scripts/upload.py /path/to/document.pdf

# 带标题和标签
python3 scripts/upload.py file.pdf --title "发票 2024" --tag "发票,2024"

# 完整元数据
python3 scripts/upload.py file.pdf \
  --title "Office Supplies Invoice" \
  --tag "expense,office" \
  --type "Receipt" \
  --correspondent "Amazon" \
  --created "2024-01-15"

# 批量上传
python3 scripts/upload.py *.pdf --tag "批量导入"

🔍 搜索文档

# 全文搜索
python3 scripts/search.py --query "发票"

# 按标签搜索
python3 scripts/search.py --tag "发票,2024"

# 按文档类型搜索
python3 scripts/search.py --type "Invoice"

# 按日期范围搜索
python3 scripts/search.py --created-after "2024-01-01" --created-before "2024-12-31"

# 组合搜索
python3 scripts/search.py --query "rent" --tag "2024" --type "Receipt"

# 限制结果数量
python3 scripts/search.py --query "invoice" --limit 20

🏷️ 标签管理

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

# 创建新标签
python3 scripts/tags.py --create "重要文档" --color "#ff0000"

# 创建带匹配规则的标签
python3 scripts/tags.py --create "发票" --color "#00ff00" --match "invoice"

# 删除标签
python3 scripts/tags.py --delete 5

📄 文档操作

# 查看文档详情
python3 scripts/documents.py --get 123

# 下载文档
python3 scripts/documents.py --download 123 --output ~/Downloads/document.pdf

# 更新文档元数据
python3 scripts/documents.py --update 123 --title "新标题" --tag "已审核"

# 添加标签
python3 scripts/documents.py --update 123 --add-tag "已归档"

# 移除标签
python3 scripts/documents.py --update 123 --remove-tag "待处理"

# 删除文档（移至回收站）
python3 scripts/documents.py --delete 123

# 永久删除
python3 scripts/documents.py --delete 123 --permanent

📋 批量操作

# 批量添加标签
python3 scripts/bulk.py --add-tag "123,456,789" --tag "已审核"

# 批量删除
python3 scripts/bulk.py --delete $(python3 scripts/search.py --query "draft" --json | jq -r '.[].id')

# 批量更新文档类型
python3 scripts/bulk.py --set-type "123,456,789" --type "Invoice"

常见工作流

1. 发票处理流程

# 上传发票
DOC_ID=$(python3 scripts/upload.py invoice.pdf --title "2024-01 发票" --tag "待处理" --json | jq -r '.id')

# 查看 OCR 提取的内容
python3 scripts/documents.py --get $DOC_ID --content

# 更新标签
python3 scripts/documents.py --update $DOC_ID --tag "已审核,已归档"

2. 批量导入和整理

# 批量上传
for file in ~/Downloads/*.pdf; do
  python3 scripts/upload.py "$file" --tag "待分类"
done

# 查看待分类文档
python3 scripts/search.py --tag "待分类"

# 逐个处理并分类
python3 scripts/documents.py --update 123 --tag "发票,2024" --type "Invoice"

3. 文档清理

# 查找重复文档
python3 scripts/search.py --query "duplicate"

# 批量删除重复项
python3 scripts/bulk.py --delete $(python3 scripts/search.py --query "duplicate" --json | jq -r '.[].id')

4. 月度文档归档

# 查找本月文档
python3 scripts/search.py --created-after "2024-01-01" --created-before "2024-01-31"

# 批量添加月度标签
python3 scripts/bulk.py --add-tag "$(python3 scripts/search.py --created-after "2024-01-01" --created-before "2024-01-31" --json | jq -r '.[].id | join(",")')" --tag "2024-01"

错误处理

认证错误

❌ Error: 401 Unauthorized
解决：检查 API Token 是否正确
# 本地部署用户，使用 local.md 中的配置
source <(cat /Users/yangtao/.openclaw/workspace/skills/paperless-ngx/local.md | grep export)

网络错误

❌ Error: Connection refused
解决：确认 Paperless-NGX 服务正在运行
# 测试本地实例
curl http://PAPERLESS_HOST:8000/api/

文件不存在

❌ Error: File not found: /path/to/file.pdf
解决：检查文件路径是否正确
ls -la /path/to/file.pdf

速率限制

❌ Error: 429 Too Many Requests
解决：等待后重试，脚本会自动处理指数退避

高级功能

智能标签建议

# 基于文档内容建议标签（使用 OpenClaw AI）
python3 scripts/documents.py --suggest 123

文档类型检测

# 自动检测文档类型
python3 scripts/upload.py document.pdf --auto-detect-type

Webhook 集成

文档参考 references/webhooks.md 了解如何设置 Webhook 集成。

导出功能

# 导出文档元数据为 CSV
python3 scripts/export.py --format csv --output documents.csv

# 导出为 JSON
python3 scripts/export.py --format json --output documents.json

配置文件（可选）

对于多实例配置，创建 ~/.config/paperless-ngx/config.json：

{
  "instances": {
    "home": {
      "url": "https://paperless-home.example.com",
      "token": "token1",
      "default_type": "Document",
      "default_tags": ["inbox"]
    },
    "work": {
      "url": "https://paperless-work.example.com",
      "token": "token2",
      "default_type": "Invoice",
      "default_tags": ["work", "invoices"]
    }
  },
  "active_instance": "home"
}

然后使用：

python3 scripts/upload.py file.pdf --instance work

故障排查

上传失败

1. 检查文件大小（Paperless-NGX 默认限制 100MB）
2. 确认文件格式支持（PDF、图片、Office 文档）
3. 检查磁盘空间

搜索无结果

1. 确认 OCR 已完成（异步操作）
2. 检查搜索语法
3. 尝试更宽泛的查询

标签不生效

1. 确认标签 ID 正确
2. 检查标签权限
3. 查看错误日志

API 参考

详细的 API 文档请参考：

• references/api-endpoints.md - 完整 API 端点参考
• references/document-types.md - 文档类型定义
• references/error-codes.md - 错误代码和解决方案

🏷️ 标签体系规范

核心原则

1. 技术标签全中文 - 所有技术领域标签使用中文
2. 3-5 个标签 - 精简但足够描述文档
3. 由宽到窄 - 领域层级：大类 → 中类 → 具体技术
4. 避免过于宽泛 - 不使用"深度学习"等过大的标签

标签层级结构

第一层：应用领域（最宽）

• 机器人 - 所有机器人相关
• 导航 - 所有导航相关
• 视觉 - 计算机视觉、3D视觉
• 大模型 - LLM、多模态大模型
• 生成模型 - 扩散模型、生成式AI

第二层：具体方向（中类）

机器人子类：

• 人形机器人
• 四足机器人
• 机器人控制

导航子类：

• 路径规划
• 运动规划
• 城市导航
• 社交导航

视觉子类：

• 3D重建
• 场景重建
• 神经渲染
• 多模态

学习方法子类：

• 强化学习
• 模仿学习
• 端到端学习
• 仿真到现实
• 域随机化

第三层：技术细节（窄）

• 注意力机制
• Transformer
• 世界模型
• 高斯泼溅
• 点云

标注规则

必选标签（2-3个）：

1. 年份 (必选) - 论文发表年份，格式：2016 - 2025 等
   • 用于按时间线追踪研究趋势
   • 便于年度归档和回顾
   • 支持年份范围筛选
2. 一级领域 (必选) - 机器人 / 导航 / 视觉 / 大模型 / 生成模型
3. 重要性 (可选) - ⭐必读（仅重要论文）

可选标签（1-2个）： 4. 二级方向 - 具体子领域（人形机器人、强化学习等） 5. 技术细节 - 具体算法/方法（Transformer、世界模型等）

总计：3-5个标签

📅 年份标签使用说明

年份标签范围： 2016 - 2025（根据实际论文发表年份）

获取年份的方法：

1. arXiv 论文 - 从 arXiv ID 推断（如 2303.xxxxx 表示 2023 年 3 月）
2. 会议论文 - 从会议名称和年份推断（如 CoRL 2024）
3. 期刊论文 - 从期刊发表日期获取
4. 未知年份 - 通过浏览器搜索论文标题查找发表年份

年份标签颜色： 统一使用灰色系 (#808080)，便于视觉识别

示例：

• 2016 - 早期经典论文（如 PPO、GAE）
• 2017 - 重要基础算法（如 PPO 算法原论文）
• 2020-2023 - 中期研究论文
• 2024-2025 - 最新前沿研究

标签组合示例

示例 1：人形机器人强化学习论文（2025年最新）

# 上传时打标签
python3 scripts/upload.py paper.pdf --title "论文标题" \
  --tag "2025,⭐必读,机器人,人形机器人,强化学习,仿真到现实"

示例 2：视觉导航论文（2024年）

python3 scripts/upload.py paper.pdf --title "论文标题" \
  --tag "2024,导航,视觉,路径规划,Transformer"

示例 3：扩散模型论文（2024年）

python3 scripts/upload.py paper.pdf --title "论文标题" \
  --tag "2024,机器人控制,强化学习,生成模型,扩散模型"

示例 4：3D重建论文（2024年）

python3 scripts/upload.py paper.pdf --title "论文标题" \
  --tag "2024,视觉,3D重建,场景重建,高斯泼溅"

示例 5：经典论文（2017年 PPO算法）

python3 scripts/upload.py paper.pdf --title "Proximal Policy Optimization Algorithms" \
  --tag "2017,⭐必读,强化学习,机器人控制"

标签映射表（旧标签 → 新标签）

| 旧标签 | 新标签 | 处理方式 | |--------|--------|----------| | 机器人与控制 | 机器人 | 简化 | | 深度学习 | ~~删除~~ | 过于宽泛，不使用 | | End-to-End Learning | 端到端学习 | 中文化 | | Imitation Learning | 模仿学习 | 中文化 | | Sim2Real | 仿真到现实 | 中文化 | | Cross-Modal | 多模态 | 中文化 | | Path Planning | 路径规划 | 中文化 | | Motion Planning | 运动规划 | 中文化 | | Gaussian Splatting | 高斯泼溅 | 中文化 | | Vision-Guided | ~~删除~~ | 并入具体技术标签 | | Robot Control | 机器人控制 | 中文化 |

标注流程

1. 确定年份 (必选) - 通过 arXiv ID、会议信息或网络搜索确定论文发表年份
2. 选一级领域 (必选) - 机器人/导航/视觉/大模型/生成模型
3. 选二级方向 (可选) - 人形机器人/强化学习/路径规划...
4. 加技术细节 (可选) - Transformer/点云/世界模型...
5. 标记重要性 (可选) - 重要文档加 ⭐必读

注意事项：

• 年份标签必须准确，可通过 arXiv、Google Scholar、官方论文页面验证
• 如果无法确定年份，使用浏览器搜索论文标题 + "arXiv" 或 "pdf"
• 创建文档时如果不确定，可先不标记年份，后续补充

---

最佳实践

1. 命名约定：使用一致的文档标题格式（如 "YYYY-MM-DD 描述"）
2. 标签层级：遵循上述标签体系规范，3-5个标签，由宽到窄
3. 定期备份：定期导出文档元数据
4. 权限管理：为不同用途创建不同的 API Token
5. 监控任务：检查上传任务的执行状态

示例场景

个人财务管理

# 上传发票并自动分类
python3 scripts/upload.py receipt.pdf --title "Amazon 2024-01-15" --tag "支出,购物,Amazon"

# 月底汇总
python3 scripts/search.py --tag "2024-01,支出" --export

企业文档管理

# 合同归档
python3 scripts/upload.py contract.pdf --type "Contract" --correspondent "供应商A" --tag "合同,2024,有效"

# 合同到期提醒
python3 scripts/search.py --type "Contract" --tag "即将到期"

学术研究

# 论文归档
python3 scripts/upload.py paper.pdf --title "论文标题 - 作者" --tag "研究,AI,论文"

# 按主题整理
python3 scripts/search.py --tag "研究" --export

---

配置文件

本地配置

对于本地部署，配置信息存储在 local.md 中：

• 实例地址: http://PAPERLESS_HOST:8000
• API Token: YOUR_TOKEN_HERE
• 部署类型: 局域网部署

详细配置和加载方法请查看：local.md

多实例配置

对于多实例配置，创建 ~/.config/paperless-ngx/config.json：

{
  "instances": {
    "home": {
      "url": "https://paperless-home.example.com",
      "token": "token1",
      "default_type": "Document",
      "default_tags": ["inbox"]
    },
    "work": {
      "url": "https://paperless-work.example.com",
      "token": "token2",
      "default_type": "Invoice",
      "default_tags": ["work", "invoices"]
    }
  },
  "active_instance": "home"
}

然后使用：

python3 scripts/upload.py file.pdf --instance work

---

技术支持

遇到问题？

1. 检查 references/error-codes.md
2. 查看 Paperless-NGX 官方文档
3. 启用详细日志：export PAPERLESS_DEBUG=1
4. 查看本地配置：cat local.md

---

Skill 版本: 1.0.0 最后更新: 2026-02-05 兼容性: Paperless-NGX 2.0+ 本地配置: local.md