The Ultimate TinyClaw Setup Guide

Category 01

Agent Won't Start

The agent isn't running or keeps crashing on launch. Check tmux, systemd, and port conflicts.

1.1

tmux Session Missing

Symptoms

tmux attach -t tinyclaw returns "no session". Agent appears offline in Telegram.

Diagnosis

bash

tmux ls
# If no "tinyclaw" session is listed, it's gone

Fix

bash

# Re-run the restart script
~/tinyclaw-restart.sh

# Verify it's back
tmux attach -t tinyclaw

Prevention

Ensure the systemd user service is enabled (Phase 06). It auto-restarts tmux sessions after reboots and crashes.

1.2

systemd Service Failed

Symptoms

systemctl --user status tinyclaw.service shows failed or inactive (dead).

Diagnosis

bash

systemctl --user status tinyclaw.service
journalctl --user -u tinyclaw.service --no-pager -n 30

Fix

bash

# Reset the failed state and restart
systemctl --user reset-failed tinyclaw.service
systemctl --user restart tinyclaw.service

Prevention

Check journalctl logs after every reboot to catch service failures early. Add a daily cron job that checks service status and alerts you.

1.3

TinyClaw Crash Loop

Symptoms

Service restarts repeatedly. Logs show rapid start/stop cycles with errors like EADDRINUSE or missing config.

Diagnosis

bash

journalctl --user -u tinyclaw.service --since "10 min ago"
tinyclaw logs all | tail -50

Fix

Stop the service, fix the underlying issue (usually a config error or port conflict), then restart.

bash

systemctl --user stop tinyclaw.service

# Fix the issue (check config, kill port conflicts)
tinyclaw config validate

# Restart once fixed
systemctl --user start tinyclaw.service

1.4

Port Conflicts

Symptoms

error output

Error: listen EADDRINUSE: address already in use :::3000

Diagnosis

bash

sudo lsof -i :3000

Fix

bash

# Kill the process holding the port
sudo kill -9 <PID>

# Or use a different port in TinyClaw config

Prevention

Before starting TinyClaw, kill any leftover dev servers. If you're running other Node apps, use different ports.

Category 02

SSH & Access Issues

Locked out of your droplet, Tailscale problems, or SSH key misconfigurations.

2.1

Locked Out After Hardening

Symptoms

ssh youruser@droplet-ip returns Connection refused or Permission denied. You disabled password auth and public SSH.

Fix

Use the DigitalOcean web console (Droplets → your droplet → Access → Launch Recovery Console).

recovery console

# Re-enable SSH temporarily to fix keys
sudo ufw allow OpenSSH
sudo ufw reload

# Fix your authorized_keys file
nano /home/youruser/.ssh/authorized_keys

# Once you can SSH in via Tailscale, re-lock
sudo ufw delete allow OpenSSH
sudo ufw reload

Prevention

Always keep a second terminal open when making SSH/firewall changes. Test the new config before closing your session.

2.2

Tailscale Auth Key Expired

Symptoms

Tailscale shows NeedsLogin in status. The machine disappeared from your Tailscale admin panel.

Diagnosis

bash

sudo tailscale status

Fix

Re-authenticate via the DigitalOcean console (since SSH over Tailscale is down).

recovery console

sudo tailscale up
# Follow the auth URL in your browser

Prevention

In the Tailscale admin panel, disable key expiry for your droplet's machine entry. Go to Machines → your droplet → Disable key expiry.

2.3

SSH Key Permissions Wrong

Symptoms

error output

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Permissions 0644 for '/home/youruser/.ssh/authorized_keys' are too open.

Fix

bash

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chown -R $(whoami):$(whoami) ~/.ssh

2.4

Can't Connect After Reboot

Symptoms

Droplet rebooted (manually or via unattended-upgrades) and Tailscale SSH isn't accepting connections.

Diagnosis

recovery console

sudo systemctl status tailscaled
sudo tailscale status

Fix

recovery console

sudo systemctl enable tailscaled
sudo systemctl start tailscaled
sudo tailscale up
sudo tailscale set --ssh

Prevention

Verify tailscaled is enabled on boot with systemctl is-enabled tailscaled. It should show enabled.

Category 03

Claude Code Problems

Authentication failures, context window issues, and API rate limits.

3.1

Auth Token Expired

Symptoms

Claude Code returns 401 Unauthorized or "Invalid API key". Agent stops responding to tasks.

Fix

bash

# Re-authenticate Claude Code
claude
# Follow the browser auth flow

# Then restart TinyClaw
systemctl --user restart tinyclaw.service

Prevention

Use a Max plan or API key with no expiry for long-running agents. Session-based auth tokens expire and need periodic renewal.

3.2

Context Window Exhaustion

Symptoms

Agent starts producing incoherent or repetitive output mid-task. Responses lose context of earlier instructions.

Fix

Break the task into smaller pieces. Send a new message to reset the conversation context.

telegram message

@coder /clear
@coder Continue from step 3 of the auth refactor. Here's the current state: [paste relevant context]

Prevention

Keep tasks focused — one feature or fix per conversation. Use todo.md to track multi-step work across sessions.

3.3

Agent Hangs / Unresponsive

Symptoms

Agent accepted a task but hasn't responded in 10+ minutes. Heartbeat still pinging but no work output.

Diagnosis

bash

tmux attach -t tinyclaw
# Check if the process is stuck or waiting for input

Fix

bash

# In the tmux session, send Ctrl+C to interrupt
# Then restart TinyClaw
~/tinyclaw-restart.sh

3.4

API Rate Limits

Symptoms

error output

Error: 429 Too Many Requests - Rate limit exceeded. Please retry after 60 seconds.

Fix

Wait for the rate limit window to reset (usually 60 seconds). The agent should auto-retry, but if it doesn't:

bash

# Restart after waiting a minute
sleep 60
systemctl --user restart tinyclaw.service

Prevention

Use a higher-tier API plan. Avoid running multiple agents with the same API key simultaneously. Space out large batch tasks.

Category 04

TinyClaw Channel Disconnects

Telegram bot stopped responding, webhooks went stale, or messages aren't getting through.

4.1

Telegram Bot Revoked

Symptoms

Messages to the bot get no response. Bot shows "Bot is not running" in BotFather or the Telegram app.

Diagnosis

bash

tinyclaw status
# Check if the Telegram channel shows "disconnected"

Fix

Regenerate the bot token in BotFather and update TinyClaw config.

bash

# Update the bot token in TinyClaw
tinyclaw config set telegram.token "NEW_BOT_TOKEN_HERE"
systemctl --user restart tinyclaw.service

4.2

Webhook Stale

Symptoms

Bot was working but stopped receiving messages. No error logs, just silence.

Fix

bash

# Reset the Telegram webhook
tinyclaw channel reconnect telegram

# Verify it's receiving
tinyclaw logs channel

4.3

Channel Not Receiving Messages

Symptoms

TinyClaw is running and connected, but your messages in Telegram aren't reaching the agent.

Diagnosis

bash

tinyclaw logs channel | tail -20
# Look for "message received" or errors

Fix

Ensure you're messaging the correct bot and that the chat ID matches the configured channel. Re-run setup if needed:

bash

tinyclaw channel setup telegram

Prevention

After any TinyClaw update, verify the channel connection with tinyclaw status and send a test message.

Category 05

Disk & Resource Issues

Running out of disk space, memory, or CPU on a small droplet.

5.1

Disk Full

Symptoms

Writes fail with No space left on device. Builds fail, logs stop writing, git operations break.

Diagnosis

bash

df -h
du -sh ~/* | sort -rh | head -10

Fix

bash

# Clear old logs
sudo journalctl --vacuum-time=3d

# Remove unused node_modules
find ~ -name node_modules -type d -prune -exec rm -rf {} +

# Clean npm/yarn cache
npm cache clean --force

# Prune Docker if used
docker system prune -af

Prevention

Set up a weekly cron job to clean logs and caches. Monitor disk usage with df -h as part of daily ops.

5.2

OOM Kills on $6 Droplet

Symptoms

Processes randomly die. dmesg shows Out of memory: Killed process.

Diagnosis

bash

dmesg | grep -i "oom\|killed"
free -h

Fix

Add swap space to give the system breathing room.

bash

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make it permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

5.3

High CPU from Runaway Processes

Symptoms

Droplet becomes sluggish. Agent responses take much longer than usual.

Diagnosis

bash

top -bn1 | head -15
# Look for processes using >50% CPU

Fix

bash

# Kill the runaway process
kill -9 <PID>

# If it's a Node process from a hung build
pkill -f "node.*build"

Category 06

Git & Deployment Failures

Credential errors, push rejections, and build failures on the droplet.

6.1

Git Credential Errors

Symptoms

error output

remote: Support for password authentication was removed.
fatal: Authentication failed for 'https://github.com/...'

Fix

bash

# Authenticate with GitHub CLI
gh auth login

# Or set up the credential helper
gh auth setup-git

6.2

Push Rejected

Symptoms

error output

! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs

Fix

bash

# Pull remote changes first
git pull --rebase origin main

# Resolve any conflicts, then push
git push origin main

Prevention

Have the agent always pull before pushing. Never force-push from the agent — if there's a conflict, let it escalate to you.

6.3

EAS Build Failures

Symptoms

eas build fails with credential errors, provisioning profile issues, or build server timeouts.

Diagnosis

bash

eas build:list --limit 5
# Check the build logs for the failed build

Fix

bash

# Re-authenticate EAS
eas login

# Clear credentials and rebuild
eas credentials
eas build --platform ios --clear-cache

6.4

Branch Conflicts from Agent

Symptoms

Agent created commits that conflict with your local work, or pushed to the wrong branch.

Fix

bash

# See what the agent changed
git log --oneline -10

# Cherry-pick good commits to a clean branch
git checkout -b clean-branch main
git cherry-pick <good-commit-hash>

Prevention

Configure the agent to always work on feature branches, never directly on main. Include this rule in AGENTS.md.

Category 07

Agent Self-Modification Recovery

The agent modified its own config or environment and broke itself. Here's how to recover.

7.1

Agent Changed Its Own Config

Symptoms

Agent behavior changed unexpectedly. It's ignoring rules, using wrong models, or acting outside its defined role.

Diagnosis

bash

# Check if config files were modified
ls -la ~/.tinyclaw-workspace/AGENTS.md
git -C ~/.tinyclaw-workspace diff

Fix

bash

# Restore from git
cd ~/.tinyclaw-workspace
git checkout -- AGENTS.md
systemctl --user restart tinyclaw.service

7.2

Agent Broke Its Environment

Symptoms

Agent installed/removed packages, changed PATH, or modified shell config. Tools no longer work.

Diagnosis

bash

# Check recent changes to shell config
git diff ~/.bashrc
which node npm claude tinyclaw

Fix

bash

# Restore shell config
cp ~/.bashrc.bak ~/.bashrc
source ~/.bashrc

# If no backup exists, rebuild the PATH
echo 'export PATH="$HOME/.local/bin:$HOME/.nvm/versions/node/v24.0.0/bin:/usr/local/bin:/usr/bin:/bin"' >> ~/.bashrc

Prevention

Keep a backup of .bashrc with cp ~/.bashrc ~/.bashrc.bak before letting the agent run. Add "never modify shell config" to your AGENTS.md safety rules.

7.3

Full Recovery from Git Backup

Symptoms

Workspace is in an unrecoverable state. Agent has made too many changes to untangle.

Fix

bash

# Stop the agent
systemctl --user stop tinyclaw.service

# Find the last known-good commit
cd ~/.tinyclaw-workspace
git log --oneline -20

# Reset to that commit
git reset --hard <good-commit-hash>

# Restart
systemctl --user start tinyclaw.service

7.4

Resurrection Script in Practice

If you set up the resurrection script from Phase 06, use it to automate recovery.

bash

# The restart script handles tmux + TinyClaw
~/tinyclaw-restart.sh

# Verify the agent is responding
tinyclaw status
# Send a test message via Telegram

Prevention

Push workspace backups to a private GitHub repo daily. Add a cron job: 0 4 * * * cd ~/.tinyclaw-workspace && git push origin main

Category 08

Network & Firewall

UFW conflicts with Tailscale, DNS issues, and outbound request failures.

8.1

UFW Blocking Tailscale

Symptoms

Can't reach the droplet via Tailscale after enabling UFW. Connection times out.

Diagnosis

recovery console

sudo ufw status verbose
# Check for rules allowing tailscale0 interface

Fix

recovery console

sudo ufw allow in on tailscale0
sudo ufw allow 41641/udp
sudo ufw reload

8.2

DNS Resolution Failures

Symptoms

npm install, git clone, or API calls fail with getaddrinfo ENOTFOUND or Could not resolve host.

Diagnosis

bash

nslookup github.com
cat /etc/resolv.conf

Fix

bash

# Add reliable DNS servers
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

Prevention

If using Tailscale's MagicDNS, ensure it's not conflicting with the system DNS resolver. Check the Tailscale admin panel DNS settings.

8.3

Outbound Requests Blocked

Symptoms

Agent can't reach external APIs (Anthropic, GitHub, npm registry). Connections time out or get refused.

Diagnosis

bash

curl -v https://api.anthropic.com
sudo ufw status

Fix

Ensure outbound traffic is allowed. Your UFW config should have default allow outgoing.

bash

sudo ufw default allow outgoing
sudo ufw reload

Prevention

Never set default deny outgoing unless you have a specific allowlist. The agent needs outbound access to APIs, package registries, and GitHub.

Troubleshooting Guide

tmux Session Missing

systemd Service Failed

TinyClaw Crash Loop

Port Conflicts

Locked Out After Hardening

Tailscale Auth Key Expired

SSH Key Permissions Wrong

Can't Connect After Reboot

Auth Token Expired

Context Window Exhaustion

Agent Hangs / Unresponsive

API Rate Limits

Telegram Bot Revoked

Webhook Stale

Channel Not Receiving Messages

Disk Full

OOM Kills on $6 Droplet

High CPU from Runaway Processes

Git Credential Errors

Push Rejected

EAS Build Failures

Branch Conflicts from Agent

Agent Changed Its Own Config

Agent Broke Its Environment

Full Recovery from Git Backup

Resurrection Script in Practice

UFW Blocking Tailscale

DNS Resolution Failures

Outbound Requests Blocked