As an AI agent using OneClaw,
I want to access Google Workspace services (Gmail, Calendar, Tasks, Contacts, Drive, Docs, Sheets, Slides, Forms) through authenticated API tools,
so that I can manage the user’s email, calendar events, tasks, contacts, files, documents, spreadsheets, presentations, and forms on their behalf.
Typical Scenarios
The user asks the agent to check their unread emails. The agent calls gmail_search with query is:unread and returns a summary of recent unread messages.
The user says “Schedule a meeting with Alice tomorrow at 2pm.” The agent calls calendar_create_event with the appropriate date, time, and attendee.
The user asks “What tasks do I have due this week?” The agent calls tasks_list_tasks and filters for tasks with due dates in the current week.
The user says “Find John Smith’s phone number.” The agent calls contacts_search with the name and returns matching contact details.
The user asks to upload a local file to Google Drive. The agent calls drive_upload with the file path and target folder.
The user says “Create a new spreadsheet with a budget template.” The agent calls sheets_create and then sheets_update_values to populate the template.
The user asks “What are the responses to my feedback form?” The agent calls forms_list_responses and summarizes the results.
The user says “Draft a reply to the latest email from my boss.” The agent calls gmail_search to find the email, reads it with gmail_get_message, then calls gmail_create_draft with the reply.
The user asks “Share the Q1 report with the marketing team.” The agent calls drive_search to find the file, then drive_share to add permissions.
The user says “Add a slide about revenue to my presentation.” The agent calls slides_add_slide and uses the Google Slides API to add content.
Feature Description
Overview
FEAT-030 adds Google Workspace integration to OneClaw, providing ~89 tools across 10 Google services. This is a port from the proven oneclaw-1 plugin system, adapted to shadow-4’s architecture (JS tool groups with QuickJS execution engine).
The feature includes:
BYOK OAuth Authentication – Users bring their own GCP OAuth Client ID and Secret for secure, self-managed authentication
10 Google Service Tool Groups – Each service is a JSON+JS asset pair registered as a JS tool group
Settings UI – Google Account configuration and sign-in management
Architecture Overview
User
| Configure OAuth credentials in Settings
| Sign in via browser OAuth flow
v
GoogleAuthManager [NEW - Kotlin, handles OAuth flow]
|
+-- EncryptedSharedPreferences (stores tokens)
|
v
AI Model
| tool call: gmail_search(query="is:unread") ...
v
ToolExecutionEngine (unchanged)
|
v
ToolRegistry
| JS Tool Group: google_gmail
| JS Tool Group: google_calendar
| JS Tool Group: google_tasks
| ... (10 groups total)
v
JsExecutionEngine (MODIFIED)
|
+-- GoogleAuthBridge [NEW] -- google.getAccessToken()
+-- FileTransferBridge [NEW] -- downloadToFile(), uploadMultipart()
+-- FetchBridge (existing) -- fetch()
+-- FsBridge (existing) -- fs.*
+-- ConsoleBridge (existing) -- console.*
|
v
QuickJS Runtime
| Executes google_{service}.js
| Calls Google Workspace REST APIs
v
Google Workspace APIs
|
v
Results returned to AI Model
10 Google Services
1. Google Gmail (18 tools)
Tool
Description
gmail_search
Search messages using Gmail query syntax
gmail_get_message
Get full content of a specific message
gmail_send
Send a new email (plain text and HTML)
gmail_reply
Reply to an existing email thread
gmail_delete
Move messages to Trash (batch, max 1000)
gmail_list_labels
List all labels/folders
gmail_get_thread
Get all messages in a thread
gmail_modify_labels
Add/remove labels on messages
gmail_batch_modify
Batch modify labels on multiple messages
gmail_list_drafts
List drafts
gmail_get_draft
Get a specific draft
gmail_create_draft
Create a new draft
gmail_send_draft
Send an existing draft
gmail_delete_draft
Delete a draft
gmail_create_label
Create a new label
gmail_delete_label
Delete a label
gmail_get_attachment
Download an attachment
gmail_history
Get mailbox change history
2. Google Gmail Settings (11 tools)
Tool
Description
gmail_list_filters
List all Gmail filters
gmail_create_filter
Create a filter (criteria + action)
gmail_delete_filter
Delete a filter by ID
gmail_get_vacation
Get vacation responder settings
gmail_set_vacation
Set/update vacation responder
gmail_list_forwarding
List forwarding addresses
gmail_add_forwarding
Add a forwarding address
gmail_get_auto_forward
Get auto-forwarding settings
gmail_set_auto_forward
Enable/disable auto-forwarding
gmail_list_send_as
List send-as aliases
gmail_list_delegates
List delegates
3. Google Calendar (11 tools)
Tool
Description
calendar_list_events
List upcoming events (default: 7 days, primary calendar)
Get form structure (items, question types, options)
forms_list_responses
List submitted responses with summary
forms_get_response
Get a specific response with all answers
BYOK OAuth Authentication
OneClaw uses a BYOK (Bring Your Own Key) OAuth flow. The user provides their own GCP Desktop OAuth Client ID and Client Secret, giving them full control over their credentials and API access.
OAuth Flow
1. User opens Settings > Google Account
2. User enters their GCP OAuth Client ID and Client Secret
3. User taps "Save Credentials"
4. User taps "Sign In with Google"
5. App starts a loopback HTTP server on a random port (127.0.0.1:{port})
6. App opens browser with Google OAuth consent URL:
- client_id, redirect_uri=http://127.0.0.1:{port}
- scope = all 11 Workspace scopes
- access_type=offline, prompt=consent
7. User grants permissions in the browser
8. Browser redirects to http://127.0.0.1:{port}?code=...
9. Loopback server captures the authorization code
10. App exchanges the code for tokens (POST https://oauth2.googleapis.com/token)
11. App fetches user email (GET https://www.googleapis.com/oauth2/v2/userinfo)
12. App stores refresh token + access token + expiry + email in EncryptedSharedPreferences
13. Settings UI updates to show signed-in state with user email
A new “Google Account” settings item is added to the Settings screen, navigating to a dedicated Google Account configuration screen.
Google Account Settings Screen
Client ID field – Text input for the user’s GCP OAuth Client ID
Client Secret field – Password-masked text input for the Client Secret
Save Credentials button – Stores credentials in EncryptedSharedPreferences
Sign In with Google button – Initiates the OAuth flow (enabled only after credentials are saved)
Signed-in state – Shows the connected Google account email and a “Sign Out” button
Status indicators – Shows configuration status (not configured / credentials saved / signed in)
User Interaction Flows
Initial Setup Flow
1. User: Opens Settings > Google Account
2. UI: Shows empty Client ID and Client Secret fields
3. User: Enters their GCP OAuth credentials and taps "Save"
4. UI: Shows "Credentials saved" confirmation, enables "Sign In" button
5. User: Taps "Sign In with Google"
6. System: Opens browser for Google OAuth consent
7. User: Grants permissions in browser
8. UI: Shows signed-in state with email (e.g., "user@gmail.com")
Using Google Tools Flow
1. User: "Check my unread emails"
2. AI: Calls gmail_search(query="is:unread", max_results=10)
3. JS Engine: Executes google_gmail.js::gmailSearch()
a. Gets access token via google.getAccessToken()
b. Calls Gmail API: GET /gmail/v1/users/me/messages?q=is:unread
c. Returns formatted message list
4. AI: Summarizes unread emails for the user
Token Refresh Flow (Transparent)
1. AI calls any Google tool
2. google.getAccessToken() is called in JS
3. GoogleAuthManager checks token expiry
4. If expired (within 60s margin): refreshes using refresh_token
5. Returns valid access token
6. Tool proceeds with API call
Acceptance Criteria
Must pass (all required):
BYOK OAuth flow: user can enter GCP Client ID + Secret, sign in, and get tokens
Access tokens are automatically refreshed when expired
All 89 tools across 10 services are registered in ToolRegistry as JS tool groups
Each tool group has a valid JSON definition file and JS implementation file