macOS App Onboarding

Overview

This guide describes the first-run onboarding experience for Clawdbot's macOS application, covering setup from initial launch through agent bootstrap.

Setup Flow

The onboarding follows 8 steps:

Step 1: Welcome

Initial welcome screen with security notice about Clawdbot's capabilities.

Step 2: Gateway Selection

Choose your Gateway mode:

Step 3: Authentication

For local setups, authenticate with your AI provider:

• Anthropic OAuth - For Claude Pro/Max subscribers
• Anthropic API Key - Direct API access
• OpenAI - GPT models
• Other Providers - Various options

The OAuth flow opens your browser for PKCE authentication. Paste the code/state value when prompted.

Credentials stored in: ~/.clawdbot/credentials/oauth.json

Step 4: Setup Wizard

Gateway-driven configuration for:

• Port and network settings
• Channel integrations
• Skill installation

Step 5: Permissions

macOS requires explicit permission grants:

Grant permissions as prompted. Some features require specific permissions to function.

Step 6: CLI Installation

Optional installation of the global clawdbot command:

# Installed to /usr/local/bin/clawdbot
clawdbot --version

Step 7: Onboarding Chat

A dedicated session for agent introduction:

• Agent creates workspace (~/.clawdbot/workspace)
• Seeds initial files: AGENTS.md, BOOTSTRAP.md, IDENTITY.md, USER.md
• Conducts Q&A to personalize your experience
• Learns your preferences and use cases

Step 8: Ready

Setup complete. You can now:

• Chat with your assistant
• Configure additional channels
• Install skills
• Customize your workspace

Gateway Modes

Local Mode

• Gateway runs on your Mac
• OAuth flows work directly
• Credentials stored locally
• Best for personal use

Remote Mode

When using a remote Gateway:

• All credentials reside on the Gateway host
• Workspace files are on the remote machine
• Local Mac acts as a client only
• Useful for shared or server deployments

Agent Bootstrap

On first run, the agent:

1. Creates workspace directory
2. Seeds instruction files
3. Conducts personalization Q&A
4. Configures initial preferences

Bootstrap Files

Troubleshooting

Permission Issues

If features don't work:

1. Open System Preferences → Privacy & Security
2. Check each permission category
3. Ensure Clawdbot is enabled
4. Restart the app if needed

OAuth Failures

If authentication fails:

1. Check your internet connection
2. Verify your subscription status
3. Try manual API key entry
4. Check ~/.clawdbot/credentials/ for issues

Gateway Won't Start

1. Check if port 18789 is available
2. Review logs in /tmp/clawdbot/
3. Try clawdbot health from terminal

Next Steps

• Setup Guide - Detailed configuration
• Building an Assistant - Create your assistant
• Channels - Connect messaging platforms