Files

Knowit c6f9530b5f docs: add BYO-KEY.md (self-hosted service-account option)

For users who don't want to share an SA credential with the rest of the team
(privacy concerns, third-party adopters, sensitive expenses), BYO-KEY.md
walks through creating their own service account: GCP project + Sheets API +
SA creation + JSON download + pointing config.json at the new key. Same code
path as the default install — the change is purely in service_account_path.

Honest about the trade-off: ~15 extra minutes vs ~5, plus rotation
responsibility moves to the user. Links to both READMEs as an opt-in
alternative.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-11 11:52:28 +08:00

6.3 KiB

Raw Permalink Blame History

AutoACCT for OpenClaw

English | 简体中文

一个 OpenClaw skill，把小票照片（可附文字说明）自动变成 Google Sheet 里结构化的一行记录，并按当日 ECB 汇率换算为港币。

目前在 OpenClaw 中手动调用；后续计划接入 WhatsApp webhook 实现真正的"发张图就记账"。

功能

用视觉识别读取小票 / 发票 / 支付截图。
提取：日期、商家、分类、金额、币种、支付方式、商品明细、原始 OCR 文本、用户备注。
通过 frankfurter.app（免费，无需 API key）按当日 ECB 参考汇率换算为 HKD。
向已配置好的 Google Sheet 追加一行（14 列，具体见 schema.md）。
回复记账结果，并标注任何靠推测填入的字段。

安装（用户端）

仓库里自带了团队的 Google service-account 密钥，已用 AES-256 加密。管理员只需给你一样东西：解密 passphrase（一般在团队密码管理器里）。

按下面 4 步操作，约 5 分钟。

不太熟悉命令行？ 用 DEPLOY.md（英文）—— 同样的安装流程，但是为非技术用户写的逐步指南，可配合 AI agent 一步步操作。

不想跟团队共用同一个 service account？ 见 BYO-KEY.md（英文）—— 自己建一个，更私有，但多花 ~15 分钟做 GCP 设置。

Step 1 — Clone 仓库 + 装 Python 依赖

git clone https://github.com/CharlesZhang2023/AutoACCT.git ~/.openclaw/workspace/skills/AutoACCT
cd ~/.openclaw/workspace/skills/AutoACCT
pip install google-api-python-client google-auth

Step 2 — 解密内置的 service-account 密钥

bash scripts/decrypt-key.sh

会提示你输入 passphrase。成功后脚本会把解出的 JSON 写到 ~/.config/gcp/bookkeeping-sa.json（权限 600），并打印 service-account 邮箱 —— 复制下来，Step 3 要用。

打开 https://sheets.new（直接创建空白 sheet）
给 sheet 起个标题（如 我的 AutoACCT 账本）
记住左下角 tab 的名字 —— 英文界面默认 Sheet1，中文界面默认 工作表1，Step 4 要用这个精确字符串

点进 A1 单元格，粘贴下面这一整行（中间是 Tab 分隔，粘进去会自动拆到 A1–N1）：

Date	Merchant	Category	Amount	Currency	Amount (HKD)	FX Rate	FX Date	Payment Method	Line Items	Raw OCR	Note	Receipt	Logged At

右上角 Share → 粘贴 Step 2 decrypt-key.sh 打印出来的 service-account 邮箱 → 权限选 Editor → Send（"Notify people" 可以不勾）
从浏览器地址栏直接复制 sheet 的完整 URL，类似： https://docs.google.com/spreadsheets/d/1abc...xyz/edit#gid=0 （脚本会自动从 URL 里抽出 sheet ID，所以完整链接或裸 ID 都行。）

Step 4 — 写 config.json

cd ~/.openclaw/workspace/skills/AutoACCT
cp config.example.json config.json

用编辑器打开 config.json，把 Step 3 拿到的 sheet_id（粘 URL 即可）和 worksheet（tab 名）填进去：

{
  "sheet_id": "https://docs.google.com/spreadsheets/d/1abc...xyz/edit",
  "worksheet": "Sheet1",
  "service_account_path": "~/.config/gcp/bookkeeping-sa.json",
  "hkd_fx_provider": "frankfurter"
}

常见坑：如果你的 Google Sheets 界面是中文，默认 tab 名是 工作表1，不是 Sheet1。必须写成 "worksheet": "工作表1"。tab 名不对会报 HTTP 400: Unable to parse range。

冒烟测试

echo '{"date":"2026-04-20","merchant":"TEST","category":"Other","amount":1,"currency":"HKD","amount_hkd":1,"fx_rate":1,"fx_date":"2026-04-20"}' | python3 ~/.openclaw/workspace/skills/AutoACCT/scripts/append_row.py

看到 OK 'Sheet1'!A2:N2（或中文 tab 名）并且 sheet 第 2 行出现 TEST，就全通了。完事记得把这行测试数据删掉。

遇到报错可以参考 scripts/setup.md 的故障排查。

管理员一次性配置

完整管理员指南见 scripts/setup.md，加密机制说明见 secrets/README.md。简版：

建 GCP 项目 → 启用 Sheets API → 建 service account → 下载 JSON key
用强随机 passphrase 加密 JSON，把 secrets/bookkeeping-sa.json.enc commit 进仓库（openssl 一行命令见 secrets/README.md）
把 passphrase 存到团队密码管理器，告诉用户按上面 4 步装
成员离职时轮换 passphrase；passphrase 或解密后的 JSON 有泄露风险时，轮换底层 GCP key

使用

在 OpenClaw 会话里把小票图片拖进来，然后说 "log this" / "记一下" 之类即可。Skill 会根据"小票/记账"类请求自动触发，不需要 slash command。

文字说明可选，可用来补充上下文（支付方式、AA、分类提示、备注等）。

文件结构

文件	作用
`SKILL.md`	入口文件 — OpenClaw 读它来决定如何执行 skill
`categories.md`	固定的 14 个分类列表
`schema.md`	Google Sheet 列顺序（A–N）
`config.example.json`	配置模板 → 复制为 `config.json`（已 gitignore）
`scripts/fx_convert.py`	原币种 → HKD 换算（frankfurter.app）
`scripts/append_row.py`	向 Google Sheet 写入一行
`scripts/decrypt-key.sh`	解密内置 SA key 到 `~/.config/gcp/`
`scripts/setup.md`	管理员配置指南 + 故障排查
`secrets/bookkeeping-sa.json.enc`	团队 SA key，AES-256 加密（可安全 commit）
`secrets/README.md`	加密机制说明 + 轮换流程
`DEPLOY.md`	面向非技术用户的逐步安装指南（英文）
`BYO-KEY.md`	可选：自建 SA 代替共享 key 的指南（英文）

6.3 KiB Raw Permalink Blame History Unescape Escape