How to Connect Google Sheets to OpenClaw

A service account is a special Google account for machine-to-machine authentication. Unlike a regular Google account, it has no browser login — it authenticates using a cryptographic key stored in a JSON file. This is the recommended authentication method for server-to-server API access. Steps to create the service account: 1. Go to console.cloud.google.com and create a new project (or select an existing one). 2. In the navigation menu, go to 'APIs & Services' > 'Library'. Search for 'Google Sheets API' and click 'Enable'. 3. Go to 'APIs & Services' > 'Credentials'. Click 'Create Credentials' > 'Service account'. 4. Give the service account a name (e.g., 'openclaw-sheets') and click 'Done'. 5. Click on the newly created service account in the list, go to the 'Keys' tab, click 'Add Key' > 'Create new key' > 'JSON'. Download the JSON file — this is your GOOGLE_SERVICE_ACCOUNT_KEY. 6. Note the service account's email address (format: openclaw-sheets@your-project.iam.gserviceaccount.com) — you will use this to share your spreadsheet with the service account. Store the downloaded JSON file in a secure location on your machine, not in a public repository. The JSON file contains a private key and must be treated as a secret credential.

1# The downloaded service account JSON file looks like this:
2{
3  "type": "service_account",
4  "project_id": "your-project-id",
5  "private_key_id": "key-id-here",
6  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
7  "client_email": "openclaw-sheets@your-project.iam.gserviceaccount.com",
8  "client_id": "123456789",
9  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
10  "token_uri": "https://oauth2.googleapis.com/token",
11  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
12  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
13}
14
15# Store this file at: ~/.openclaw/secrets/google-service-account.json
16mkdir -p ~/.openclaw/secrets
17chmod 700 ~/.openclaw/secrets  # restrict access to owner only

The service account needs explicit sharing permission on each Google Sheet it will access — service accounts do not have implicit access to files in your Google Drive. This is an important security feature: the service account can only access sheets you explicitly share with it. To share the sheet: 1. Open your Google Sheet in the browser. 2. Click 'Share' in the top-right corner. 3. In the 'Add people and groups' field, paste the service account's email address (found in the JSON key file as `client_email`, e.g., `openclaw-sheets@your-project.iam.gserviceaccount.com`). 4. Set the permission level to 'Editor' if OpenClaw needs to write to the sheet, or 'Viewer' for read-only access. 5. Uncheck 'Notify people' (the service account cannot receive email). 6. Click 'Share'. Also note the Spreadsheet ID from the URL. The URL format is: `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`. Copy the SPREADSHEET_ID — it is the long alphanumeric string between `/d/` and `/edit`.

1# Extract spreadsheet ID from URL:
2# URL: https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit
3# Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
4
5# Verify service account has access (test with curl after setup):
6curl -s -X GET \
7  'https://sheets.googleapis.com/v4/spreadsheets/YOUR_SPREADSHEET_ID?fields=properties' \
8  -H "Authorization: Bearer $(python3 -c "
9import json, time, jwt
10creds = json.load(open('/Users/$(whoami)/.openclaw/secrets/google-service-account.json'))
11now = int(time.time())
12claim = {'iss': creds['client_email'], 'scope': 'https://www.googleapis.com/auth/spreadsheets', 'aud': 'https://oauth2.googleapis.com/token', 'iat': now, 'exp': now + 3600}
13print(jwt.encode(claim, creds['private_key'], algorithm='RS256'))
14")"

Open `~/.openclaw/config.yaml` and add the Google Sheets integration under the `integrations` key. Configure the path to the service account JSON file and the default spreadsheet ID. You can specify the credentials either as a file path (`credentials_file`) or as inline JSON (`credentials_json`). The file path approach is recommended for security — the JSON file stays on disk with restricted permissions rather than being embedded in the config file. The `default_spreadsheet_id` is the spreadsheet OpenClaw uses when no other ID is specified in a workflow action. You can override this on a per-action basis if you use multiple spreadsheets. The `default_sheet_name` is the name of the tab/worksheet within the spreadsheet. Google Sheets creates a first sheet named 'Sheet1' by default. If your spreadsheet has multiple tabs (e.g., 'Research', 'Logs', 'Reports'), set the one you want OpenClaw to use by default. Run `clawhub reload` after saving the config to apply the changes.

1# ~/.openclaw/config.yaml
2integrations:
3  google-sheets:
4    credentials_file: "~/.openclaw/secrets/google-service-account.json"
5    # OR provide inline JSON:
6    # credentials_json: '{"type": "service_account", ...}'
7    default_spreadsheet_id: "YOUR_SPREADSHEET_ID"
8    default_sheet_name: "Sheet1"    # tab name within the spreadsheet
9    value_input_option: "USER_ENTERED"  # 'USER_ENTERED' or 'RAW' for values
10    append_dimension: "ROWS"            # append new rows (default) or COLUMNS
11    date_time_format: "YYYY-MM-DD HH:mm:ss"  # format for date values

Test the full integration by reading the existing spreadsheet content and writing a test row. These tests confirm that authentication is working, the service account has the correct permissions, and data flows correctly between OpenClaw and Google Sheets. The read test fetches a range of cells from the spreadsheet and returns the values. The write test appends a new row with test data. After writing, open the Google Sheet in the browser and verify the new row appears. Google Sheets uses A1 notation for ranges: `Sheet1!A1:E10` means rows 1-10, columns A-E, on the sheet named 'Sheet1'. If you are appending rows without caring about column count, use `Sheet1!A:Z` as the range for append operations — Google Sheets automatically extends the data range. The Sheets API has a free quota of 300 read requests per minute and 300 write requests per minute. For most OpenClaw workflows that write a few rows per hour, you will never approach this limit.

1# Test reading from the spreadsheet:
2curl -X GET \
3  'https://sheets.googleapis.com/v4/spreadsheets/YOUR_SPREADSHEET_ID/values/Sheet1!A1:E5' \
4  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
5# Returns: {"range": "Sheet1!A1:E5", "values": [["col1", "col2", ...], ...]}
6
7# Test appending a row:
8curl -X POST \
9  'https://sheets.googleapis.com/v4/spreadsheets/YOUR_SPREADSHEET_ID/values/Sheet1!A:Z:append?valueInputOption=USER_ENTERED' \
10  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
11  -H 'Content-Type: application/json' \
12  -d '{
13    "values": [["2026-03-30", "OpenClaw test", "Integration working", "SUCCESS"]]
14  }'
15
16# Expected response:
17# {"updates": {"updatedRange": "Sheet1!A2:D2", "updatedRows": 1, "updatedColumns": 4}}

With the connection verified, configure OpenClaw workflows that automatically write data to Google Sheets based on events. The most common pattern is a post-task logging workflow that appends a row with structured data after each OpenClaw task completes. Design your spreadsheet columns before building the workflows — decide what data you want to capture and in what order. Common columns for research logging: Date, Time, Query, Summary, Source Count, Sources, Status. For task tracking: Timestamp, Task Name, Duration (seconds), Status, Output. The workflow config maps OpenClaw's task output variables to specific column values. The `values` array defines the row to append — each item in the array maps to a column, in the order they appear from left to right in the sheet. For higher-volume workflows, use OpenClaw's batch append feature to write multiple rows at once rather than one row per task — this reduces API calls and is more efficient when logging frequently.

1# ~/.openclaw/config.yaml — Google Sheets logging workflows
2workflows:
3  research-log-to-sheets:
4    trigger:
5      type: task-complete
6      task_type: web-search
7    actions:
8      - type: google-sheets-append
9        integration: google-sheets
10        spreadsheet_id: "YOUR_SPREADSHEET_ID"
11        sheet_name: "Research Log"
12        values:
13          - "{{date:YYYY-MM-DD}}"
14          - "{{time:HH:mm:ss}}"
15          - "{{trigger.query}}"
16          - "{{trigger.summary}}"
17          - "{{trigger.source_count}}"
18          - "{{trigger.sources | join: ', '}}"
19          - "SUCCESS"
20
21  task-completion-tracker:
22    trigger:
23      type: workflow-complete
24    actions:
25      - type: google-sheets-append
26        integration: google-sheets
27        sheet_name: "Task Log"
28        values:
29          - "{{timestamp:iso}}"
30          - "{{trigger.workflow_name}}"
31          - "{{trigger.duration_seconds}}"
32          - "{{trigger.status}}"
33          - "{{trigger.error_message | default: ''}}"
34
35  batch-data-write:
36    trigger:
37      type: task-complete
38      task_type: data-extraction
39    actions:
40      - type: google-sheets-batch-append
41        integration: google-sheets
42        sheet_name: "Extracted Data"
43        rows: "{{trigger.extracted_records}}"
44        column_map: ["name", "price", "category", "url", "extracted_at"]