Paperless-ngx

通过 Paperless-ngx REST API 进行文档管理。

配置

在~/.clawdbot/clawdbot.json中设置环境变量：

{
  "env": {
    "PAPERLESS_URL": "http://your-paperless-host:8000",
    "PAPERLESS_TOKEN": "your-api-token"
  }
}

或通过技能条目配置（允许使用apiKey速记）：

{
  "skills": {
    "entries": {
      "paperless-ngx": {
        "env": { "PAPERLESS_URL": "http://your-paperless-host:8000" },
        "apiKey": "your-api-token"
      }
    }
  }
}

从 Paperless 网页界面获取您的 API 令牌：设置 → 用户与群组 → [用户] → 生成令牌。

快速参考

所有脚本位于{baseDir}/scripts/目录下。

常见工作流

查找文档

# Full-text search
node {baseDir}/scripts/search.mjs "electricity bill december"

# Filter by tag
node {baseDir}/scripts/search.mjs --tag "tax-deductible"

# Filter by document type
node {baseDir}/scripts/search.mjs --type "Invoice"

# Filter by correspondent
node {baseDir}/scripts/search.mjs --correspondent "AGL"

# Combine filters
node {baseDir}/scripts/search.mjs "2025" --tag "unpaid" --type "Invoice"

获取文档详情

# Metadata only
node {baseDir}/scripts/get.mjs 28

# Include OCR text content
node {baseDir}/scripts/get.mjs 28 --content

# Full content (no truncation)
node {baseDir}/scripts/get.mjs 28 --content --full

上传文档

# Basic upload (title auto-detected)
node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf

# With metadata
node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf \
  --title "AGL Electricity Jan 2026" \
  --tags "unpaid,utility" \
  --type "Invoice" \
  --correspondent "AGL" \
  --created "2026-01-15"

下载文档

# Download to current directory
node {baseDir}/scripts/download.mjs 28

# Specify output path
node {baseDir}/scripts/download.mjs 28 --output ~/Downloads/document.pdf

# Get original (not archived/OCR'd version)
node {baseDir}/scripts/download.mjs 28 --original

管理元数据

# List all tags
node {baseDir}/scripts/tags.mjs

# List document types
node {baseDir}/scripts/types.mjs

# List correspondents
node {baseDir}/scripts/correspondents.mjs

# Create new tag
node {baseDir}/scripts/tags.mjs --create "new-tag-name"

# Create new correspondent
node {baseDir}/scripts/correspondents.mjs --create "New Company Name"

输出格式

所有脚本均输出 JSON 以便于解析。可使用jq工具进行格式化：

node {baseDir}/scripts/search.mjs "invoice" | jq '.results[] | {id, title, created}'

高级用法

对于复杂查询或批量操作，请参阅references/api.md用于直接API访问模式。

故障排除

"未设置PAPERLESS_URL"— 添加到~/.clawdbot/clawdbot.json的env部分或在shell中导出。

"401 未授权"— 检查PAPERLESS_TOKEN是否有效。如有需要，请在Paperless UI中重新生成。

"连接被拒绝"— 确认Paperless正在运行且URL正确（包含端口）。

上传静默失败— 检查Paperless日志；文件可能是重复的或不支持的格式。