Google Sheets API 技能（高级版）

目的

为 OpenClaw 提供一个可用于生产环境的 Google Sheets 命令行界面。此技能支持数据读写、批量操作、格式设置和工作表管理，并使用服务账户进行身份验证。

最佳适用场景

• 您需要一个可重复使用的命令行界面来处理自动化任务。
• 您希望为数据处理流程提供 JSON 输入/JSON 输出。
• 您需要的不只是基本的读写操作（格式设置、工作表操作、批量更新）。

不适用场景

• 您必须使用最终用户 OAuth 同意流程（此技能主要面向服务账户）。
• 您只需要进行轻量级、一次性的编辑。

一次性设置

1. 创建或选择一个 Google Cloud 项目。
2. 启用 Google Sheets API。
3. 创建一个服务账户并下载其 JSON 密钥。
4. 与服务账户电子邮件共享目标电子表格。

安装

cd google-sheet-api
npm install

运行

node scripts/sheets-cli.js help
node scripts/sheets-cli.js read <spreadsheetId> "Sheet1!A1:C10"
node scripts/sheets-cli.js append <spreadsheetId> "Sheet1!A:B" '@data.json'

您也可以使用 npm：

npm run sheets -- read <spreadsheetId> "Sheet1!A1:C10"

凭据

支持的来源（首次匹配优先）：

• GOOGLE_SHEETS_CREDENTIALS_JSON（内联JSON字符串）
• GOOGLE_SERVICE_ACCOUNT_KEY（文件路径）
• GOOGLE_SHEETS_KEY_FILE（文件路径）
• GOOGLE_APPLICATION_CREDENTIALS（文件路径）
• ./service-account.json、./credentials.json、./google-service-account.json
• ~/.config/google-sheets/credentials.json

输入约定

• JSON值可以是内联的，也可以通过@路径从文件加载。
• 写入/追加操作期望一个二维值数组。

示例data.json：

[["Name","Score"],["Alice",95]]

命令映射（高级）

数据：

• 读取,写入,追加,清空,批量获取,批量写入

格式化：

• 格式化,获取格式,边框,合并,取消合并,复制格式

布局：

• 调整大小,自动调整大小,冻结

工作表：

• 创建、信息、添加工作表、删除工作表、重命名工作表

高级功能：

• 批量操作（原始spreadsheets.batchUpdate请求）

操作指南

• 在可能的情况下，对于读取工作流优先使用只读范围。
• 对于429和临时性5xx错误，采用指数退避策略进行重试。
• 保持请求负载较小，以避免限制问题。

预期输出

• 将JSON输出到标准输出；错误时返回非零退出代码。

安全注意事项

• 切勿记录或提交服务账户密钥。
• 仅与此技能所需的服务账户邮箱共享电子表格。