OC
OpenClaw
Dashboard

TOOLS.md

/home/ubuntu/.openclaw/workspace/TOOLS.md
Back

TOOLS.md - Local Notes

Skills define how tools work. This file is for your specifics — the stuff that's unique to your setup.

Coding task defaults

  • Prefer Claude Code for coding tasks.
  • Run it with --dangerously-skip-permissions unless snake explicitly instructs otherwise.
  • Before starting a new coding task, pull first (e.g., git pull in the relevant repo) unless told not to.
  • When we update files in the workspace, commit and push those changes (unless you tell me not to, or it’s a throwaway/experimental branch).
    • Practical rule: if I used write/edit on a workspace file, I should immediately run git status → then git add -A && git commit && git push in the same turn.

X/Twitter (Timeline Summaries) via bird

Goal: summarize snake’s Following timeline from this EC2 instance.

Working setup (EC2)

  • Store X session cookies as env vars in: ~/.config/bird/credentials.env
    • Contains AUTH_TOKEN and CT0 (do not commit; permissions chmod 600).
  • Usage:
    • source ~/.config/bird/credentials.env
    • bird check
    • bird query-ids --fresh (fixes stale GraphQL query IDs)
    • bird home --following -n 200 --json

Common failure modes + fixes

  • Tried --chrome-profile-dir and it couldn’t find/decrypt cookies

    • Symptom: Failed to read Linux keyring via secret-tool; v11 cookies may be unavailable and/or No Twitter cookies found
    • Cause: Chromium cookies on Linux are often encrypted via keyring/libsecret; copied cookie DBs won’t decrypt on EC2.
    • Fix: pass cookies directly via env vars (AUTH_TOKEN, CT0) or flags (--auth-token, --ct0).

  • Auth works but timeline calls fail

    • Run bird query-ids --fresh then retry.

  • Safety note

    • Never pass raw tokens through OpenClaw tool calls (they get logged). Prefer local file + source.

Google Workspace (gog) on EC2

Goal: read/write Google Calendar (and Gmail) via gog on the EC2 host.

Keyring prompt gotcha (OpenClaw systemd service)

If gog works in your shell but OpenClaw still prompts for a keyring password, it’s because the Gateway runs as a systemd user service and does not source ~/.bashrc.

Fix: use a systemd EnvironmentFile= to pass:

  • GOG_KEYRING_BACKEND=file
  • GOG_KEYRING_PASSWORD=...

Full writeup: docs/gog-systemd-keyring-setup.md

OAuth callback gotcha (EC2 vs laptop)

gog auth add uses a loopback redirect like:

  • http://127.0.0.1:<PORT>/oauth2/callback

If you open the auth URL on your laptop while gog is running on EC2, Google redirects to the laptop’s 127.0.0.1, so EC2 never receives the callback.

Fix: SSH local port-forward from laptop to EC2 (use the port printed in the URL):

  • ssh -L <PORT>:127.0.0.1:<PORT> ubuntu@<ec2-host>

Then re-open the auth URL on the laptop.

Keyring / passphrase

After auth, gog stores tokens in an encrypted keyring:

  • Prompt: Enter passphrase to unlock "/home/ubuntu/.config/gogcli/keyring"

On headless EC2, new gog processes may prompt again because there’s no GUI keychain agent.

Tip: run gog inside a persistent tmux session and unlock once for that session.

Config

  • gog auth keyring file writes: /home/ubuntu/.config/gogcli/config.json with { "keyring_backend": "file" }

What Goes Here

Note to self (OpenClaw setup/config work)

When working on OpenClaw setup/config/gateway/tailscale issues: read the relevant docs first (local docs under workspace/docs/ when available, otherwise https://docs.openclaw.ai) before making config changes.

Note to self (openclaw-dashboard)

  • If I push commits to /home/ubuntu/projects/openclaw-dashboard, I should restart the dashboard service so the running Next.js instance picks up the new build:
    • sudo systemctl restart openclaw-dashboard.service
  • Reason: the 5-min update timer only restarts when it pulls new commits; local commits can leave the service running an older build until restarted.

Convention: document new setups

Whenever we set up something new that affects the environment (services, timers, networking, automation, cron, deploy pipelines, etc.), write a short doc under:

  • /home/ubuntu/.openclaw/workspace/docs/

Include:

  • goal
  • what was changed/installed
  • file paths (systemd units, scripts, configs)
  • how to check status/logs
  • how to disable/remove

Cron / automation conventions

  • If a script primarily supports an OpenClaw Gateway cron job, put it under:
    • /home/ubuntu/.openclaw/workspace/automation/**
  • Exception: if the cron job is operating on a different project repo (e.g. committing to ai-compass or openclaw-dashboard), keep the script in that repo’s scripts/ folder.
  • Reference: docs/automation-conventions.md

Guardrail: never edit global OpenClaw packages

  • Do not modify files under /home/ubuntu/.npm-global/lib/node_modules/openclaw/** (or any globally installed OpenClaw package).
  • If behavior needs changing, prefer:
    1. editing cron payloads / local scripts in /home/ubuntu/.openclaw/workspace, or
    2. updating OpenClaw via the normal update/install path, or
    3. upstreaming a PR.
  • Treat global package edits as forbidden unless snake explicitly asks.

Things like:

  • Docs convention: put assistant-authored docs, specs, and how-tos under /home/ubuntu/.openclaw/workspace/docs/ (i.e., /workspace/docs) so they’re easy to find and don’t clutter the repo root.

  • Camera names and locations

  • SSH hosts and aliases

  • Preferred voices for TTS

  • Speaker/room names

  • Device nicknames

  • Anything environment-specific

Add whatever helps you do your job. This is your cheat sheet.