This document covers the initial setup of Clawdbot on a fresh Ubuntu host and connecting it to the services you’ll use day-to-day.

GTD workflow (task lists, daily/weekly rituals, prompts, templates) is intentionally deferred to a Day 2 doc.

0) What you’re building

A personal assistant that:

  • runs as a daemon (Gateway) on a server
  • talks to you over Telegram
  • can access Google Workspace (Gmail/Calendar/Tasks/Drive)
  • optionally integrates with GitHub

Useful links:

1) Host / infrastructure

1.1 Choose a host

Any always-on machine works. I used an Ubuntu instance on AWS EC2.

Minimum practical sizing:

  • CPU: 1–2 vCPU
  • RAM: 2GB+
  • Disk: >= 20GB recommended (small root volumes fill up surprisingly fast)

1.2 OS prep

sudo apt-get update
sudo apt-get install -y curl ca-certificates git

2) Install Node.js + Clawdbot

2.1 Install Node.js (v22+)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v
npm -v

2.2 Install Clawdbot

npm install -g clawdbot
clawdbot --version

2.3 Run onboarding

This generates config, validates basics, and helps you connect channels.

clawdbot onboard

3) Run Clawdbot as a service (systemd)

Create a systemd unit so the gateway starts on boot and restarts on failure.

/etc/systemd/system/clawdbot.service

[Unit]
Description=Clawdbot Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
Environment=PATH=/home/ubuntu/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/ubuntu/.npm-global/bin/clawdbot gateway start --foreground
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable + start:

sudo systemctl daemon-reload
sudo systemctl enable clawdbot
sudo systemctl start clawdbot
sudo systemctl status clawdbot --no-pager

4) Telegram integration

4.1 Create a bot

  • Open Telegram → message @BotFather
  • Run /newbot
  • Save the bot token

4.2 Allowlist your user

In Clawdbot config, set:

  • the bot token
  • your Telegram user ID in allowFrom

4.3 Test

Send a DM to the bot.

5) Google Workspace integration (gog)

Clawdbot can run Google actions via the gog CLI.

5.1 Install gog

Follow: https://gogcli.sh

5.2 Google Cloud OAuth (once)

In Google Cloud Console:

  • create/select project
  • configure OAuth consent screen
  • create OAuth Client ID → Desktop app
  • download the client secret JSON

Enable APIs:

  • Gmail API
  • Google Calendar API
  • Google Tasks API
  • Google Drive API

5.3 Authenticate gog

gog auth credentials ~/path/to/client_secret.json

gog auth add [email protected] --manual
export GOG_ACCOUNT=[email protected]

# Needed on servers/headless usage
export GOG_KEYRING_PASSWORD="your-secure-password"

Sanity checks:

gog gmail messages search "newer_than:7d" --max 3

gog calendar calendars --json --no-input | head

gog tasks lists list --json --no-input

6) GitHub integration (optional)

If you want Clawdbot to help with issues/PRs/CI, install GitHub CLI:

sudo apt-get update
sudo apt-get install -y gh

gh auth login --hostname github.com --git-protocol https --web

7.1 Disk space monitoring

Tiny root volumes are a common failure mode.

  • Add a daily check of free space for / (alert when low).
  • If you’re on EC2, consider increasing the EBS volume size early.

7.2 Backups

At minimum:

  • back up your Clawdbot config
  • back up anything under your workspace directory you care about

7.3 Updates

Stick to a routine (e.g., weekly) rather than ad-hoc updates.

8) Available capabilities

Once set up, ClawdBot can:

  • Email — Search and read emails, summarize email content (send emails with additional setup)
  • Tasks — List, create, update, complete tasks; move tasks between lists; add due dates and notes
  • Drive — Create folders and documents, search files, organize content
  • GitHub — List repositories, view and create issues, check pull requests and CI status
  • General — Web search, weather forecasts, natural language interaction for all of the above

9) GDoc notes

GDoc integration is currently not fully implemented in ClawdBot. Unfortunately, gog doesn’t support inserting content into Docs directly. That’s why it’s easier to use a semi-automated workflow to make notes:

  1. Ask the bot to make notes on GDrive, which results in an MD file created
  2. Open the MD file in GDocs as a GDoc — the markup will be converted automatically
  3. Manually copy-paste (or save as) to the proper GDoc

10) Claude daily and weekly limits

I tried starting with Claude Pro at 15 GBP monthly. The Claude Pro plan has token limits that apply on a 5-hour daily level and on a weekly level. While weekly limits are pretty gracious, I was hitting the 5-hour limit constantly. I added an extra 25 GBP to the budget per month for limit extension, but it gets spent very quickly while you do setup. I hope it will become less hungry when I switch to daily activities, once setup is completed.

How to optimize limits: Usage limits best practices

I need to be wise balancing note-writing between different agents:

  • Use Claude for orchestration and GTD
  • Use Gemini or ChatGPT for refining notes, which is a lot of text (tokens)
  • Use Claude Code or Codex for coding

11) Solving Gemini API integration

A key goal was to use Google’s Gemini models. We hit a snag where the API calls would fail, causing a fallback to other models.

  • Problem: The bot reported “No API key found for provider ‘google’”, even though the key was correctly placed in the configuration files.
  • Investigation: We confirmed the key was valid using a direct curl test. The breakthrough came from inspecting the bot’s Go source code (src/agents/model-auth.ts).
  • Solution: The code revealed that the application expects the environment variable for the Google provider to be named GEMINI_API_KEY, not the more generic GOOGLE_API_KEY we were using. Renaming the variable in clawdbot.json immediately solved the problem.

12) Authorizing Google Tasks on a headless server

Integrating with Google Tasks from a command-line tool on a remote server presented a significant OAuth challenge.

  • Problem: The gog CLI tool, when built from source, uses a generic, unverified Google OAuth Client ID. Google’s security flow for such apps expects a browser on the same machine as the CLI to complete the authorization, which is impossible on a headless server. The command would hang, waiting for a browser redirect that could never arrive.
  • The Bypass (Manual OAuth Handshake): We devised a workaround to complete the flow manually.
    1. Generated a User-Owned Credential: A new OAuth 2.0 Client ID for a “Desktop app” was created in the user’s own Google Cloud Console.
    2. Configured the CLI: The downloaded client_secret.json was used to configure the gog tool, giving it a trusted identity.
    3. Captured the Callback: The authorization process was initiated on the server, which printed an auth URL. The user opened this URL in their local browser, approved the permissions, and was redirected to a failing 127.0.0.1 page.
    4. Delivered the Code Manually: The user copied the entire failed URL (which contained the ?code=... parameter) and sent it to the bot.
    5. Completed the Handshake: Using curl on the server, we made a GET request to that full URL. This successfully delivered the authorization code to the mini web server that gog was running locally, completing the handshake.

This solution allowed us to authorize a CLI tool on a remote server in a situation where it was fundamentally designed for a local desktop.

13) Next steps

Planned enhancements:

  • Daily digest of tasks and calendar
  • Weekly review automation
  • Calendar integration for reminders
  • News/social media digest
  • Apple Health integration