OpenClaw电子凭证自动入账_完整教程
开头
每天,财务部门都要处理大量的电子发票、银行回单、电子回单。这些电子凭证需要人工查验、匹配科目、生成凭证、归档保存。
一个中等规模的企业,每月可能有500-1000张电子凭证。如果每张处理需要5分钟,那就是40-80小时的工作量。
OpenClaw能不能帮我们解决这个痛点?
答案是:能。而且只需要一个插件。
今天,我带你完整部署一个电子凭证自动入账OpenClaw插件,实现从发票查验到凭证归档的全流程自动化。
注意:本文是纯技术教程,不讨论新会计法或合规政策。我们只讲”怎么做”。
一、插件功能总览
1.1 电子凭证入账能做什么?
这个插件提供三大核心能力:
-
发票查验:自动对接税务总局平台,批量查验发票真伪 -
自动入账:根据发票内容智能匹配会计科目,生成标准记账凭证 -
自动归档:将电子凭证和生成的凭证归档到企业云盘/本地目录
完整流程:
电子发票PDF → 解析信息 → 查验真伪 → 匹配科目 → 生成凭证JSON → 归档存储
1.2 技术架构与依赖
该插件基于 OpenClaw 技能开发框架,架构如下:
通过
不通过
电子发票PDF
OCR解析(pdf2image + tesseract)
提取关键字段发票号、金额、税额…
查验真伪(税务总局API)
查验结果
匹配会计科目(规则引擎)
异常队列人工复核
生成凭证JSON(符合会计制度)
归档存储(本地/云盘)
完成
依赖组件:
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1.3 适用场景与前提条件
适用企业:
-
有电子发票自动化需求 -
已有OpenClaw环境(或愿意部署) -
有税务总局查验接口权限(IP白名单)
前提条件:
-
OpenClaw 2.0+ 已安装 -
Python 3.9+ 环境 -
已申请税务总局发票查验接口(或使用第三方服务) -
归档目录可写(本地盘或云盘)
二、安装与配置
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
该脚本会:
-
检查Python依赖,自动安装 -
创建数据目录( data/、logs/) -
初始化数据库表结构 -
测试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 |
|
|
OCR识别率低,关键字段为空 |
|
config.yaml 中 ocr.dpi(如600) 或使用更清晰的PDF |
科目匹配错误:未找到匹配规则 |
|
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张发票慢
排查步骤:
-
查看日志中每张发票处理耗时(DEBUG级别) -
识别瓶颈: -
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%以上。
最佳实践:
-
先小批量测试:用10-20张发票跑通全流程,确认规则准确 -
复核机制:生产环境使用 --review选项,确保首月无误 -
定期备份:每日备份 invoice_voucher.db和归档目录 -
监控失败率:设置日志监控,失败率>5%时告警 -
持续优化规则:根据实际发票类型,迭代 rules.yaml
下一步扩展:
-
对接财务系统自动生成凭证 -
添加报表统计(月度入账量、查验成功率等) -
实现移动端复核界面(Web UI)
互动问题:
-
你在电子凭证入账中遇到的最大痛点是什么? -
是否需要我详细讲解某个扩展功能(如ERP对接、自定义规则)?
夜雨聆风