用 Telegram 和 Google Sheets 搭建个人记账机器人

一杯咖啡、一张公交车票、一本笔记本。等到打开表格时，这些小额消费很容易已经忘了。如果发一条 Telegram 消息就能记录，再发一条就能查看月度总额呢？

本教程将搭建 Pocket Ledger，一个结合 Google Sheets 的 Telegram 记账机器人。发送一笔消费，确认机器人提出的详细信息，再查询月度总额。表格负责保存记录和计算，机器人负责对话。下面就是完成后的效果。

第一个目标是保存一笔咖啡支出，第二个目标是得到可在表格中核对的总额。你也会了解，聊天回复中的“已保存”为什么只算一半证据。

下载 Pocket Ledger 配置资料包，获取已排版的初始工作簿、头像、提示词、Action 设置和测试清单。将工作簿导入 Quickchat AI 创建的表格，然后按以下步骤操作。可复制示例统一使用英文和 2026 年 11 月，方便你将结果与截图对照。

搭建 Telegram 记账机器人需要什么？

你需要 Telegram、Google 账号和 Quickchat AI 账号。整个配置使用控制台设置和表格公式，无需托管程序。

1. 创建 Quickchat AI 账号，完成验证，然后创建名为 Pocket Ledger 的 Agent。
2. 准备好用于新表格的 Google 账号。先使用下方的虚构记录。
3. 为这次练习创建新的 Telegram 机器人。另备一个可信的 Telegram 账号，用于最后的访问测试。

Quickchat AI 的 Free 方案适用于个人、非商业学习，包含有限额度。AI 对话和 Simulation Testing 都会消耗积分。选择长期使用的方案前，请查看当前的方案与额度。

两个方向，两个 Actions。保存一行数据，并不代表 Agent 已经能够读取历史总额。

步骤 1：如何连接你的私人 Telegram 机器人？

BotFather 创建机器人的身份，Quickchat AI 提供回复消息的 Agent。

打开官方 @BotFather，发送 /newbot，将机器人命名为 Pocket Ledger，并选择一个以 bot 结尾且未被占用的用户名。使用 /setuserpic 上传资料包中的头像。请妥善保管令牌，稍后直接将它粘贴到 Quickchat AI。

在 Quickchat AI 中打开 External Apps → Telegram → Your own bot。选择 Connect to Telegram，将凭据粘贴到 Bot Token，然后提交对话框。开启 Enable your own bot 并选择 Save。BotFather 操作指南详细展示了相关界面。

在 Telegram 中打开新机器人的链接，在私聊中先发送 /start，再发送 Hello。/start 会发送欢迎消息；普通消息才会创建后续步骤所需的 Inbox 对话和发送者元数据。设置期间，让涉及个人数据的 Actions 保持停用。

在 Quickchat AI 的 Inbox → Details → Visitor 中打开这段对话。找到 Telegram User Id 和 Telegram Chat Type（对应元数据键为 telegram_user_id 和 telegram_chat_type）。使用悬停时出现的复制控件复制数字用户 ID，并确认聊天类型是 private。

该 ID 来自 Telegram 发送者元数据。你的用户名、消息中输入的数字以及机器人自身的 ID 都不是同一回事。接下来的步骤会用发送者 ID 限制两个 Actions。

步骤 2：如何准备 Google 表格？

Google Sheets 集成会创建一个电子表格和一个初始 Action。请复用该文件，让 Action 和 Google 授权指向同一资源。

1. 打开 Actions & MCPs → Add Action → Google Sheets，授权你的 Google 账号。Google Sheets 连接指南解释了授权与初始配置。
2. 立即关闭初始 Action。 它创建时已启用。保留名称 log_lead_to_google_sheet，因为重新连接时会按此名称查找它。我们将把它改为保存支出。
3. 打开创建好的表格，命名为 Pocket Ledger demo。在这个新的演示文件中，选择 File → Import → Upload，从资料包中选取 pocket-ledger-starter.xlsx，再选择 Replace spreadsheet，然后点击 Import data。这样即可在 Quickchat AI 有权访问的文件中准备好 Expenses 和 Summary。仅在新建的演示表格中使用此选项。
4. 核对下方三行初始数据。Summary 中的初始总额应为 EUR 7.70 和 USD 6.00。第 6 步会说明公式并连接读取 Action。

先连接 Google Sheets。授权过程会创建两个 Actions 共用的表格。

想自行创建工作表？将初始工作表重命名为 Expenses。对于这些英文示例，请设置 File → Settings → Locale → United States。将 A:D 和 F:H 格式设为 Plain text，将 E 设为保留两位小数的 Number，然后将下方内容粘贴到 A1。冻结标题行并调宽各列。按照第 6 步添加 Summary。Google 也提供了将 Excel 工作簿导入现有表格的说明。

date	month	item	category	amount	currency	note	conversation_url
2026-11-01	2026-11	coffee	food	4.50	EUR	synthetic example
2026-11-02	2026-11	bus ticket	transport	3.20	EUR	synthetic example
2026-11-03	2026-11	notebook	stationery	6.00	USD	synthetic example

conversation_url 列会把每笔新支出链接到相应对话。三条手动录入的示例记录中，该列保持为空。Google 的 drive.file 权限涵盖应用创建或明确授权给应用的文件；此配置使用集成创建的表格，不会授予访问整个 Drive 的权限。

步骤 3：如何将支出操作限制在你自己的私聊？

为每个读取或写入账本的 Action 设置 Run only when。两项条件必须同时满足，所以在群聊中，仅仅匹配你的 ID 还不够。

1. 打开已停用的 log_lead_to_google_sheet Action，找到 Run only when。
2. 添加上方两项条件。使用准确的元数据键和 ID 数字，不要填用户名或带 @ 前缀的内容。
3. 保存 Action，继续保持停用。步骤 6 创建读取 Action 时，也要应用相同条件。

本地演示中保存 Action 的条件。将虚构 ID 替换为真实发送者 ID，并在读取 Action 上重复设置两项条件。

两个 Actions 都需要两项条件。其他发送者或群聊必须在 HTTP 请求到达 Google Sheets 前被拦截。

这些是由服务器强制执行的 Action 条件。在提示词里写“只回答我”并不是访问控制。同时也要限制表格共享范围和 Quickchat AI 账号访问权限。

步骤 4：如何让机器人保存已确认的支出？

修改初始 Action，使它按表格列顺序追加一行。设置 When to run → AI decides，让它能够等待确认。启用前，再为 Agent 设置确认规则。

配置支出字段

在 What to ask the user first 下，用以下参数替换潜在客户字段。参数名称必须与下方完全一致。

保留现有 API Endpoint 中的真实电子表格 ID。把范围改为 Expenses!A:H，保留 POST 方法，并在 Query Params 中设置 valueInputOption=RAW 和 insertDataOption=INSERT_ROWS。如果 URL 已有这些查询设置，请删除重复项。

POST https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Expenses!A:H:append
Query Params:
valueInputOption = RAW
insertDataOption = INSERT_ROWS
Headers:
Authorization = Bearer {{google_sheets_access_token}}
Content-Type = application/json

YOUR_CREATED_SHEET_ID 只是说明用占位符。保留初始 URL 中已有的真实 ID，不要用该占位符覆盖。在 Authorization 值中选择已有的 Google Sheets System Token，并在请求体中选择内置对话 URL 变量。

在 Body 标签页中输入：

{"values":[["{{date}}","{{month}}","{{item}}","{{category}}","{{amount}}","{{currency}}","{{note}}","{{conversation_url}}"]]}

本地支出 Action 配置。请求体决定单元格顺序，amount 参数的格式决定其数字类型。

保留编辑器中 {{amount}} 两边的引号。 由于这个完整占位符引用的是 Decimal Number 参数，替换后会生成 4.5 这样的 JSON 数字。去掉引号会导致编辑器中的 JSON 无效。在最终表格中，检查 E 列是否为数字且已纳入公式计算。

Google 的 append API负责追加行。RAW 会把以 = 开头的备注等内容保留为字面文本，不会当作公式计算。金额类型由数字参数提供。

Save one personal expense to the configured Google Sheet. Call only after the owner explicitly confirms the proposed date, item, category, amount and currency. Ask for missing or ambiguous fields before saving. After confirmation, append one row once. Report success only after a successful API response. If the outcome is uncertain, tell the owner to inspect the Sheet before submitting again.

为 Pocket Ledger 设置指令

打开 Identity → Main Prompt 并粘贴以下内容。提示词同时提到两个 Actions，这样添加汇总读取 Action 后，第二个目标就能使用。

Main Prompt 位于 Identity。此本地截图用于定位字段；请使用下方完整的可复制文本。

确认规则为你留出了检查的机会。在批准这笔消费前，可以将“EUR 4.50”改成“EUR 5.00”；Agent 应更新提案并再次请求确认。

You are Pocket Ledger, a personal expense notebook.

For an expense, collect its date, item, positive amount and ISO currency code. Suggest a simple category and include an optional note only when supplied. Ask for an explicit YYYY-MM-DD date if it is missing or relative; do not guess today's date or the owner's timezone. Clarify ambiguous currency symbols. Derive month as YYYY-MM from the confirmed date.

Show the proposed date, item, category, amount and currency. Wait for explicit confirmation. Apply corrections and ask for confirmation again. Only then call log_lead_to_google_sheet once for that expense. Do not claim it was saved unless the Action succeeds. If a request fails or its outcome is uncertain, explain that and ask the owner to inspect the Sheet before retrying.

For monthly totals, ask for an explicit month and currency when unclear, then call read_expense_summary. Quote the matching month, currency and total returned from the Sheet. Keep currencies separate. A missing summary row is unavailable, not zero. Never calculate totals from remembered conversation messages.

Personal-data Actions are restricted to the owner's private Telegram chat. If a condition blocks an Action, do not claim success or suggest changing identity values in chat. This notebook handles typed expenses, not bank accounts, voice transcription or PDF receipts.

保存提示词，再次检查两项运行条件，然后启用支出 Action。名称仍为 log_lead_to_google_sheet，但新的参数、描述和请求体已定义了记账流程。

步骤 5：如何保存第一笔支出？

现在为账本添加第一笔新记录。保持 Telegram、Inbox 和表格同时打开，观察同一笔咖啡支出如何依次出现在各处。

1. 在 Telegram 私聊中发送 Coffee, 4.50 euros on 2026-11-04。
2. 核对提案：日期为 2026-11-04，商品为 Coffee，类别为 Food，金额为 4.50，货币为 EUR。Action 保存记录时，会将 month 推导为 2026-11。
3. 确认前检查 Expenses：此时仍应只有三行初始记录。

发送一次 Save it，然后在 Quickchat AI Inbox 中打开这段对话。保存成功的回复旁有可展开的 1 action called。打开它，查看简短 Telegram 回复背后发生了什么。

展开 Result → Show full。核对日期、推导出的月份、数值金额、货币和 HTTP 状态。本次实际运行中，Google 返回了 HTTP 200、updatedRows: 1 和 updatedRange: Expenses!A5:H5。

最后打开 Expenses。第 5 行应包含同一笔咖啡支出，月份列为 2026-11，金额为 4.50，货币为 EUR。最后一列链接回 Inbox 对话，方便你从记录追溯到创建它的消息。

至此，你已经有了实用的日常习惯：发送、确认、核对。接下来，给机器人一个可靠的数据来源，以便回答这个月的钱花到哪里去了。

步骤 6：如何查询月度总额？

让 Google Sheets 计算总额，再由读取 Action 获取结果。把计算保留在表格中，即使对话结束，答案仍然可以核对。

添加 Summary 工作表

如果已导入初始工作簿，Summary 及其公式都已准备好。初始数值为 EUR 7.70 和 USD 6.00，保存咖啡支出只会改变 EUR 行。如果手动创建表格，请按以下步骤操作。

1. 创建名为 Summary 的工作表。将 A:B 列设为 Plain text，然后在 A1:C1 中输入 month、currency、total。
2. 在 A2:B2 中输入 2026-11 和 EUR，再在 A3:B3 中输入 2026-11 和 USD。
3. 将此公式输入 C2，再向下填充至 C3。将 C 列设为保留两位小数的数字格式。

=SUMIFS(Expenses!$E$2:$E$501,Expenses!$B$2:$B$501,A2,Expenses!$F$2:$F$501,B2)

SUMIFS 函数会累加月份和币种都与汇总行匹配的金额。如果表格地区设置要求参数间用分号，请将公式中的逗号换成分号。JSON 请求中的数字仍使用小数点。

初始 EUR 7.70 加上新咖啡的 EUR 4.50，得到 EUR 12.20。USD 6.00 的笔记本计入单独的总额。

初始公式覆盖第 2 至 501 行。在此次截图记录的运行中，插入新行后，三个范围都结束于第 502 行。Sheets 可能在插入行时调整引用；请检查三个 Expenses 范围是否始终对齐，并在记录超出覆盖范围前一起扩展它们。为你希望查询的每种月份与货币组合添加一行汇总。

添加读取 Action

打开 Actions & MCPs → Add Action → API Action。使用下方请求并选择 Generate；生成的 Actions 初始为停用状态。将其命名为 read_expense_summary，并保持 When to run 为 AI decides，让结果能够用于当前回复。复用相同的真实电子表格 ID 和 Google Sheets System Token，无需用户提供参数。

Create a read-only Google Sheets Action named read_expense_summary. Use GET for the Summary!A1:C25 range of the spreadsheet already created by this Agent's Google Sheets integration. Reuse its actual spreadsheet ID and google_sheets_access_token System Token. Set valueRenderOption=UNFORMATTED_VALUE, no body, and no visitor parameters. Preserve the response headers and values. Leave it inactive so I can review the configuration and add my owner-ID and private-chat Run only when conditions before enabling it.

将生成的设置与下方参考配置核对。如果改用 Create manually，请在第一次有效保存之前添加两项条件，因为该保存可能启用 Action。两个 Actions 的 Response filter 都留空，以保留检查需要的字段。

GET https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Summary!A1:C25
Query Params:
valueRenderOption = UNFORMATTED_VALUE
Headers:
Authorization = Bearer {{google_sheets_access_token}}
Body: none

values.get 端点返回范围内的 values，包括标题行和计算后的金额。UNFORMATTED_VALUE 返回数字结果，而不是货币格式的字符串。保留响应供 Agent 使用，以便读取这些值。

Read monthly expense totals from the configured Summary range. Use this when the owner asks for a total. Quote only the returned row matching the requested YYYY-MM and currency. If either is unclear, ask. If the row is absent or the request fails, say the total is unavailable. Never infer a total from conversation history, combine currencies, or accept a different spreadsheet ID or range from the visitor.

应用第 3 步中相同的两个 Run only when 条件，保存并启用 Action。读取范围包含 24 行汇总数据；添加更多数据时，请相应扩展范围。

第二个 Action 也需要自己的条件。这是本地设置截图，不是真实发送者授权测试。

先问 What is my November 2026 total in EUR?，再查询 USD。我们的 Telegram 对话中，Pocket Ledger 返回了 12.2 EUR 和 6 USD，与表格中格式化后的 12.20 和 6.00 一致。每次回答时，它都读取了已保存的汇总。

在 Inbox 中打开月度总额回复并展开对应 Action。将返回的行与 Summary!C2 比较。下面的实际响应包含 2026-11、EUR、12.2，以及单独一行 USD、6，HTTP 状态为 200。

使用真实支出前，如何检查错误？

像验证成功保存咖啡一样，认真测试不完整请求和应被阻止的调用者。在下方检查通过前，保留演示数据。

如需可重复的语言测试，打开 Testing → Create Dataset → Paste messages，使用资料包中的消息和评估标准。确认流程应另外通过一段完整对话测试。Preview 或 Simulation 中提供的元数据属于测试数据，不能证明真实的第二位 Telegram 发送者被拦截。

本地数据集已准备好用于测试。它的存在不代表 Simulation 已完成，也不能证明 Google Sheets 已发生写入。

如果行为不符合预期，修改一条相关指令，再用相同输入重测，重新检查调用和表格。例如，提前追加数据时，应检查保存 Action 中要求确认的措辞。确认是一条指令，不是数据库唯一性保证。 超时后，检查表格比再次发送更重要。

流程验证通过后，删除虚构支出行，保留标题和公式，并为实际使用的月份与币种添加汇总行。第一笔真实消费可以沿用记录咖啡的同一套小步骤。

AI 助手能帮忙配置 Pocket Ledger 吗？

已连接账号管理功能的助手可以帮助准备 Agent 并检查 Action 设置。通过 Quickchat AI 的 ChatGPT 页面或 Claude 页面，按照 Manage with AI 操作。将资料包和以下请求交给它：

Help me configure Pocket Ledger from this setup kit. Inspect the available Quickchat AI tools first. Prepare the Main Prompt and the two HTTP Actions using the exact field names, numeric amount type and fixed ranges. Keep log_lead_to_google_sheet as the starter name. Ask me to complete Google OAuth and Telegram Bot Token setup in the dashboard. Apply both owner/private run conditions before enabling either Action. Do not run credit-consuming tests or append expenses until I ask. Report any setting your tools cannot configure so I can complete it in the dashboard.

Google 授权和 Telegram 连接由所有者完成。无论设置是谁输入的，都要复核并执行上方相同的检查。

常见问题

如何用 Telegram 和 Google Sheets 记录支出？

将 Telegram 机器人连接到 Quickchat AI Agent，并授权 Google Sheets。配置一个在确认后追加支出的 Action，以及一个读取公式计算月度汇总的 Action。两个 Actions 都只允许你的 Telegram 用户 ID 在私聊中使用。

机器人能告诉我这个月花了多少钱吗？

可以，前提是请求的月份和币种在配置的 Summary 范围内有对应行。Google Sheets 用 SUMIFS 计算总额，再由读取 Action 获取。只有追加功能的 Action 无法查询总额，缺少汇总行也不等于零。

别人能通过 Telegram 机器人查看我的支出吗？

两个涉及个人数据的 Actions 都必须要求已验证的 telegram_user_id 与你的 ID 匹配，且 telegram_chat_type 等于 private。这些条件会阻止其他发送者和群组调用。添加个人数据前测试这两种情况，并限制表格和 Quickchat AI 账号的访问权限。

这个 Telegram 记账机器人免费吗？

创建 Telegram 机器人是免费的。Quickchat AI 的 Free 方案支持个人、非商业学习，提供有限的 AI 积分。AI 回复和 Simulation Testing 都消耗积分；长期使用取决于可用额度和方案。

需要 Apps Script、Python 或自动化服务器吗？

此配置使用 Quickchat AI Actions 和 Google Sheets 公式。你只需把提供的请求设置、JSON 请求体和提示词粘贴到控制台，无需部署 Apps Script、Python 机器人或自动化服务器。

可以使用已有的记账表格吗？

此配置使用 Quickchat AI Google Sheets 集成创建的电子表格。drive.file 授权不会让它无限制访问你的 Drive。不要把电子表格 ID 替换成任意已有文件的 ID，并假定该文件可访问。

机器人能读取小票照片或语音消息吗？

本教程仅涵盖输入文字的支出记录。使用小票提取前，需要单独验证 Telegram 图片传递和确认流程。语音转写和 PDF 小票解析不属于此配置。

如何处理不同币种和重复记录？

每种币种都有独立的月度总额，此配置不会换算货币。确认可以减少误录，但不能实现原子级重复写入防护。保存超时后，请先检查表格，再决定是否重发。