乐于分享
好东西不私藏

OpenClaw电子凭证自动入账_完整教程

OpenClaw电子凭证自动入账_完整教程

开头

每天,财务部门都要处理大量的电子发票、银行回单、电子回单。这些电子凭证需要人工查验、匹配科目、生成凭证、归档保存。

一个中等规模的企业,每月可能有500-1000张电子凭证。如果每张处理需要5分钟,那就是40-80小时的工作量。

OpenClaw能不能帮我们解决这个痛点?

答案是:能。而且只需要一个插件。

今天,我带你完整部署一个电子凭证自动入账OpenClaw插件,实现从发票查验到凭证归档的全流程自动化。

注意:本文是纯技术教程,不讨论新会计法或合规政策。我们只讲”怎么做”。


一、插件功能总览

1.1 电子凭证入账能做什么?

这个插件提供三大核心能力:

  1. 发票查验:自动对接税务总局平台,批量查验发票真伪
  2. 自动入账:根据发票内容智能匹配会计科目,生成标准记账凭证
  3. 自动归档:将电子凭证和生成的凭证归档到企业云盘/本地目录

完整流程

电子发票PDF → 解析信息 → 查验真伪 → 匹配科目 → 生成凭证JSON → 归档存储 

1.2 技术架构与依赖

该插件基于 OpenClaw 技能开发框架,架构如下:

通过

不通过

电子发票PDF

OCR解析(pdf2image + tesseract)

提取关键字段发票号、金额、税额…

查验真伪(税务总局API)

查验结果

匹配会计科目(规则引擎)

异常队列人工复核

生成凭证JSON(符合会计制度)

归档存储(本地/云盘)

完成

依赖组件

组件
用途
版本要求
OpenClaw Core
技能运行环境
>= 2.0.0
pdf2image
PDF转图片(用于OCR)
>= 1.16.0
tesseract-ocr
文字识别
>= 5.0.0
requests
HTTP请求(税务总局接口)
>= 2.28.0
pyyaml
配置文件解析
>= 6.0
SQLAlchemy
凭证数据库ORM
>= 2.0.0

1.3 适用场景与前提条件

适用企业

  • 有电子发票自动化需求
  • 已有OpenClaw环境(或愿意部署)
  • 有税务总局查验接口权限(IP白名单)

前提条件

  1. OpenClaw 2.0+ 已安装
  2. Python 3.9+ 环境
  3. 已申请税务总局发票查验接口(或使用第三方服务)
  4. 归档目录可写(本地盘或云盘)

二、安装与配置

2.1 环境要求

操作系统:Linux/Windows/macOS(Windows需安装tesseract)

Python环境

python --version# 应显示 3.9+ pip --version

OpenClaw环境

openclaw --version# 应显示 2.0+

2.2 下载插件

插件开源地址:https://github.com/example/openclaw-invoice-skill

克隆或下载到 OpenClaw 技能目录:

cd ~/.openclaw/skills/ git clone https://github.com/example/openclaw-invoice-skill.git # 或下载zip解压

目录结构

invoice-skill/ ├── SKILL.md              # 插件说明 ├── manifest.json         # OpenClaw技能定义 ├── requirements.txt      # Python依赖 ├── config.yaml           # 配置文件(需修改) ├── rules.yaml            # 科目匹配规则 ├── src/ │   ├── __init__.py │   ├── commands.py       # 指令定义 │   ├── invoice_parser.py # 发票解析 │   ├── verifier.py       # 查验逻辑 │   ├── account_matcher.py # 科目匹配 │   └── voucher.py        # 凭证生成 └── scripts/     └── install.sh        # 安装脚本 

2.3 修改配置文件

关键文件:config.yaml

# 税务总局查验接口配置verification:endpoint:"https://fpdk.sbggzy.bjdz.gov.cn/api/verification"# 北京税务示例app_id:"your_app_id"app_secret:"your_app_secret"timeout:10# 秒# 归档配置archive:base_path:"/data/finance/invoices"# 归档根目录structure:"year/month/day"# 目录结构backup_enabled:truebackup_path:"/backup/finance/invoices"# 数据库配置(存储已入账凭证)database:url:"sqlite:///./data/invoice_voucher.db"# 或 PostgreSQL: postgresql://user:pass@host:5432/invoice# OCR配置ocr:tesseract_cmd:"tesseract"# Windows需完整路径,如 "C:\\Program Files\\Tesseract-OCR\\tesseract.exe"lang:"chi_sim+eng"# 中英文dpi:300# 日志配置logging:level:"INFO"file:"/var/log/openclaw/invoice.log"max_size_mb:100backup_count:10

修改要点

  • verification.endpoint:替换为你的税务总局接口地址
  • verification.app_id / app_secret:填入你的接口密钥
  • archive.base_path:确保目录存在且有写权限
  • ocr.tesseract_cmd:Windows需修改为绝对路径

2.4 验证安装

执行安装脚本

cd ~/.openclaw/skills/invoice-skill ./scripts/install.sh 

该脚本会:

  1. 检查Python依赖,自动安装
  2. 创建数据目录(data/logs/
  3. 初始化数据库表结构
  4. 测试OCR可用性

验证测试

# 测试OCR openclaw invoice:test-ocr --file ./tests/sample_invoice.pdf  # 应输出识别出的文字(包含"发票号码"、"金额"等)

三、快速上手:5分钟完成第一笔入账

3.1 准备测试发票

找一张已查验过的电子发票PDF(测试用不需要真实验证),放到任意目录,例如:

C:\invoices\test_invoice.pdf 

3.2 执行入账指令

打开命令行,运行:

openclaw invoice:post "C:\invoices\test_invoice.pdf"

首次运行

  • 插件会解析PDF,提取发票信息
  • 调用税务总局接口查验(需网络)
  • 匹配会计科目(根据 rules.yaml 规则)
  • 生成凭证JSON
  • 归档到 config.yaml 配置的目录

输出示例

[INFO] 开始处理发票:test_invoice.pdf [INFO] OCR识别完成,提取字段:发票号码=12345678,金额=10000.00,税额=900.00 [INFO] 查验接口返回:一致 [INFO] 匹配科目:管理费用-办公费(6602.01) [INFO] 凭证生成成功,凭证号:V20250323001 [INFO] 归档完成:/data/finance/invoices/2025/03/23/test_invoice.pdf [SUCCESS] 入账完成! 

3.3 查看结果

凭证JSON文件(保存在数据库,也可导出):

{"voucher_no":"V20250323001","date":"2025-03-23","attachment_count":1,"entries":[{"account_code":"6602.01","account_name":"管理费用-办公费","debit":10000.00,"credit":0,"description":"电子发票12345678"},{"account_code":"2221.06","account_name":"应交税费-应交增值税(进项税额)","debit":900.00,"credit":0,"description":"进项税"},{"account_code":"1002.02","account_name":"银行存款-工行","debit":0,"credit":10900.00,"description":"付款"}],"source_invoice":"12345678","archived_path":"/data/finance/invoices/2025/03/23/test_invoice.pdf"}

数据库查看

sqlite3 ./data/invoice_voucher.db "SELECT * FROM vouchers ORDER BY created_at DESC LIMIT 1;"

四、核心指令详解

4.1 invoice:post – 单张发票入账

语法

openclaw invoice:post <发票文件路径>[选项]

选项 | 选项 | 说明 | |——|——| | --dry-run | 模拟运行,不实际入账和归档(用于测试) | | --review | 需要人工确认后才执行入账(交互模式) | | --output <文件> | 将生成的凭证JSON保存到指定文件 | | --force-reverify | 强制重新查验(默认缓存查验结果7天) |

示例

# 模拟运行,查看会发生什么 openclaw invoice:post invoice.pdf --dry-run  # 需要人工审核才入账 openclaw invoice:post invoice.pdf --review# 生成凭证并导出JSON openclaw invoice:post invoice.pdf --output voucher.json 

4.2 invoice:batch – 批量处理

语法

openclaw invoice:batch <文件夹路径>[--recursive][--parallel <并发数>]

示例

# 处理文件夹内所有PDF(不递归子文件夹) openclaw invoice:batch ./invoices/  # 递归处理所有子文件夹,最大并发5个 openclaw invoice:batch ./invoices/ --recursive--parallel5

输出:批量生成 batch_report_YYYYMMDD_HHMMSS.json

4.3 invoice:status – 查询任务状态

语法

openclaw invoice:status <任务ID>

任务ID获取

  • invoice:batch 命令的最后一行会输出任务ID,如 batch_20250323_143022
  • 数据库 batch_tasks 表可查询

示例

openclaw invoice:status batch_20250323_143022 

输出:

{"task_id":"batch_20250323_143022","total":50,"processed":32,"success":30,"failed":2,"remaining":18,"estimated_seconds":180}

五、自定义扩展

5.1 修改科目匹配规则

文件rules.yaml

默认规则示例:

rules:-name:"办公费"keywords:["办公用品","文具","纸张","打印"]account_code:"6602.01"account_name:"管理费用-办公费"tax_rate:0.06# 6%税率,自动计算税额-name:"差旅交通费"keywords:["机票","火车票","住宿","出租车"]account_code:"6602.12"account_name:"管理费用-差旅费"tax_rate:0.09# 9%税率( transportation)-name:"技术服务费"keywords:["技术服务","维护费","咨询费"]account_code:"6602.18"account_name:"管理费用-技术服务费"tax_rate:0.06

添加新规则

-name:"软件采购"keywords:["软件","SaaS","系统","平台"]account_code:"6602.28"account_name:"管理费用-软件服务费"tax_rate:0.06

匹配逻辑:插件会提取发票”货物或应税劳务名称”字段,与所有规则的 keywords 进行模糊匹配(包含即命中)。第一个匹配的规则生效。

5.2 对接企业内部ERP

在 config.yaml 中添加 ERP 配置:

erp:enabled:trueendpoint:"https://erp.yourcompany.com/api/v1/vouchers"api_key:"your_erp_api_key"auto_sync:true# 入账成功后自动同步到ERP

插件会在凭证生成后,自动调用 ERP 接口创建凭证。如需自定义同步逻辑,修改 src/voucher.py 的 sync_to_erp() 函数。

5.3 添加自定义异常处理

插槽:on_verification_failed

在 src/commands.py 中可以注册钩子:

def on_verification_failed(invoice_data, error):     """     发票查验失败时的回调     invoice_data: 发票信息字典     error: 错误信息     返回值:True表示忽略失败继续入账,False表示停止处理     """     logger.warning(f"发票{invoice_data['number']}查验失败: {error}")          # 示例:某些发票(如通行费)不走税务总局,跳过     if invoice_data.get('type') == 'toll':         logger.info("通行费发票跳过税务总局查验")         return True          return False  # 其他情况停止处理

运行

5.4 调整并发与性能参数

在 config.yaml 中:

performance:max_workers:4# 批量处理时的最大并发线程数ocr_batch_size:10# OCR批处理大小cache_verification_days:7# 查验结果缓存天数(避免重复调用)db_pool_size:10# 数据库连接池大小

六、故障排查与排错

6.1 常见问题速查

现象
可能原因
解决方案
发票查验失败:返回码500
税务总局接口不稳定或IP未白名单
1. 检查IP是否在白名单 2. 稍后重试 3. 切换备用接口(修改endpoint)
OCR识别率低,关键字段为空
扫描件质量差或dpi过低
提高 config.yaml 中 ocr.dpi(如600) 或使用更清晰的PDF
科目匹配错误:未找到匹配规则
invoice商品名称不在keywords中
1. 检查发票”货物名称”字段 2. 在 rules.yaml 添加对应关键词
生成凭证重复
发票号码已存在但未去重
插件自动查重,但历史数据需手动清理数据库后重试
归档失败:权限被拒绝
归档目录不可写
确保 archive.base_path 目录存在且有写权限

6.2 日志查看

日志位置config.yaml 中 logging.file 指定的路径,默认 /var/log/openclaw/invoice.log

实时监控

tail-f /var/log/openclaw/invoice.log 

日志级别调整:修改 config.yaml 的 logging.level 为 DEBUG 可输出详细信息。

6.3 性能调优

场景:批量处理1000张发票慢

排查步骤:

  1. 查看日志中每张发票处理耗时(DEBUG级别)
  2. 识别瓶颈: 
    • OCR慢:提高 ocr_batch_size(如50),或使用更快的OCR引擎
    • 查验慢:税务总局接口延迟高,考虑启用 cache_verification_days 缓存
    • 数据库慢:检查SQLite是否频繁磁盘写入,改为PostgreSQL

调优参数示例

performance:max_workers:8# 增加并发ocr_batch_size:20cache_verification_days:30# 延长缓存database:url:"postgresql://user:pass@localhost/invoice"# 换用PostgreSQL

七、总结与最佳实践

核心价值:本插件将电子凭证入账从人工5分钟/张,降低到自动处理(仅异常需人工复核),效率提升95%以上。

最佳实践

  1. 先小批量测试:用10-20张发票跑通全流程,确认规则准确
  2. 复核机制:生产环境使用 --review 选项,确保首月无误
  3. 定期备份:每日备份 invoice_voucher.db 和归档目录
  4. 监控失败率:设置日志监控,失败率>5%时告警
  5. 持续优化规则:根据实际发票类型,迭代 rules.yaml

下一步扩展

  • 对接财务系统自动生成凭证
  • 添加报表统计(月度入账量、查验成功率等)
  • 实现移动端复核界面(Web UI)

互动问题

  1. 你在电子凭证入账中遇到的最大痛点是什么?
  2. 是否需要我详细讲解某个扩展功能(如ERP对接、自定义规则)?

本站作品均采用知识共享署名-非商业性使用-相同方式共享 4.0进行许可,资源收集于网络仅供用于学习和交流,本站一切资源不代表本站立场,我们尊重软件和教程作者的版权,如有不妥请联系本站处理!

 沪ICP备2023009708号

© 2017-2026 夜雨聆风   | sitemap | 网站地图