# SOPHIAClaw Customer Onboarding Guide

Step-by-step guide for setting up SOPHIAClaw for the first time.

## Overview

This guide walks new customers through:

1. Installing SOPHIAClaw
2. Configuring the gateway
3. Setting up Telegram bot
4. Running the first conversation
5. Setting up workspace

**Time Requipurple**: 15-30 minutes
**Prerequisites**: Computer with internet, Telegram account

## Pre-Onboarding Checklist

Before starting, ensure you have:

- [ ] Administrative access to your computer
- [ ] Node.js 22+ installed (or willingness to install)
- [ ] Telegram account
- [ ] Approximately 30 minutes of uninterrupted time

### System Requirements

| Component | Minimum                               | Recommended   |
| --------- | ------------------------------------- | ------------- |
| Node.js   | 22.0.0                                | Latest LTS    |
| RAM       | 4 GB                                  | 8 GB          |
| Disk      | 1 GB free                             | 5 GB free     |
| OS        | macOS 12+, Ubuntu 20.04+, Windows 10+ | Latest stable |

## Step 1: Installation

### Option A: Via NPM (Recommended)

```bash
# Install globally
npm install -g sophiaclaw

# Verify installation
sophiaclaw --version
```

### Option B: Via Mac App (macOS)

1. Download from: https://sophiaclaw.ai/download
2. Move to Applications folder
3. Open and grant permissions

### Option C: Via Install Script

```bash
# macOS/Linux
curl -fsSL https://sophiaclaw.ai/install.sh | bash

# Windows (PowerShell)
iwr -useb https://sophiaclaw.ai/install.ps1 | iex
```

### Post-Installation Verification

```bash
# Check version
sophiaclaw --version

# View help
sophiaclaw --help

# Run diagnostic
sophiaclaw doctor
```

## Step 2: Initial Configuration

### Initialize SOPHIAClaw

```bash
# Create configuration directory and files
sophiaclaw init

# Verify initialization
ls -la ~/.sophiaclaw/
```

**Expected output:**

```
~/.sophiaclaw/
├── sophiaclaw.json      # Main configuration
├── .env               # Environment variables
├── logs/              # Log directory
└── credentials/       # Secure credential storage
```

### Set Gateway Mode

```bash
# Configure for local operation (recommended for beginners)
sophiaclaw config set gateway.mode local

# Verify setting
sophiaclaw config get gateway.mode
```

### Configure Bind Address

```bash
# Set to loopback (secure, local only)
sophiaclaw config set gateway.bind 127.0.0.1

# Set port (default: 37521)
sophiaclaw config set gateway.port 37521

# Review all settings
sophiaclaw config list
```

## Step 3: Telegram Bot Setup

### Create Telegram Bot

1. **Open Telegram** and search for `@BotFather`
2. **Start conversation** with BotFather
3. **Create new bot:**
   ```
   /newbot
   ```
4. **Name your bot:**
   - Display name: `MySOPHIAClaw`
   - Username: `my_sophiaclaw_bot` (must end in `bot`)
5. **Save the token** provided by BotFather
   - Format: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`

### Configure Bot Token

**Method 1: Via CLI**

```bash
# Set token (replace with your actual token)
sophiaclaw config set channels.telegram.token "YOUR_BOT_TOKEN"
```

**Method 2: Via Environment File**

```bash
# Edit .env file
echo "TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN" >> ~/.sophiaclaw/.env

# Verify
head ~/.sophiaclaw/.env
```

### Enable Telegram Channel

```bash
# Enable Telegram
sophiaclaw config set channels.telegram.enabled true

# Verify configuration
sophiaclaw channels status telegram
```

## Step 4: Start the Gateway

### Launch Gateway

```bash
# Start gateway
sophiaclaw gateway run

# Or start in background
nohup sophiaclaw gateway run > /tmp/sophiaclaw.log 2>&1 &
```

### Verify Gateway Status

```bash
# Check if running
sophiaclaw channels status --probe

# Test connectivity
curl http://127.0.0.1:37521/health

# View logs
tail -f ~/.sophiaclaw/logs/gateway.log
```

**Expected output:**

```
✓ Gateway running on 127.0.0.1:37521
✓ Telegram channel connected
✓ Health check passed
```

## Step 5: First Conversation

### Open Your Bot

1. **Search** for your bot in Telegram (e.g., `@my_sophiaclaw_bot`)
2. **Start** the conversation by clicking "Start" or sending `/start`

### Send Test Message

Try these commands:

```
/start
```

Expected: Welcome message from SOPHIAClaw

```
Hello! Can you help me?
```

Expected: AI response acknowledging your message

```
What can you do?
```

Expected: List of capabilities

### Verify Communication

Check that messages flow correctly:

1. **User → Bot**: Send message in Telegram
2. **Bot → Gateway**: Message received
3. **Gateway → AI**: Processing request
4. **AI → Gateway**: Response generated
5. **Gateway → Bot**: Response sent
6. **Bot → User**: Reply received

**Troubleshooting:**

- No response? Check `~/.sophiaclaw/logs/gateway.log`
- Delayed responses? Normal for first message (cold start)
- Errors? Run `sophiaclaw doctor`

## Step 6: Workspace Setup

### Understanding Workspaces

SOPHIAClaw organizes work into:

- **Channels**: Communication endpoints (Telegram, Discord, etc.)
- **Agents**: AI assistants with specific configurations
- **Sessions**: Individual conversations

### Configure Default Agent

```bash
# List available agents
sophiaclaw agents list

# Set default agent
sophiaclaw config set agents.default sophia

# Configure agent settings
sophiaclaw config set agents.sophia.model gpt-4o
sophiaclaw config set agents.sophia.thinking medium
```

### Set Up Conversation History

```bash
# Enable conversation persistence
sophiaclaw config set sessions.persist true

# Set retention period (days)
sophiaclaw config set sessions.retentionDays 30

# View session storage location
sophiaclaw config get sessions.path
```

### Configure Notification Preferences

```bash
# Enable notifications
sophiaclaw config set notifications.enabled true

# Set quiet hours (optional)
sophiaclaw config set notifications.quietHoursStart 22:00
sophiaclaw config set notifications.quietHoursEnd 08:00
```

## Step 7: Security Hardening (Optional)

### Enable Authentication

```bash
# Require authentication for gateway access
sophiaclaw config set gateway.auth.enabled true

# Set API key
sophiaclaw config set gateway.auth.apiKey "your-secure-key"
```

### Configure Allowed Users

```bash
# Restrict Telegram bot to specific users
sophiaclaw config set channels.telegram.allowedUsers "user1,user2"

# Or use usernames
sophiaclaw config set channels.telegram.allowedUsernames "@alice,@bob"
```

### Review Permissions

```bash
# Check file permissions
ls -la ~/.sophiaclaw/

# Ensure secure permissions
chmod 700 ~/.sophiaclaw
chmod 600 ~/.sophiaclaw/.env
```

## Verification Checklist

Complete this checklist to confirm successful onboarding:

- [ ] SOPHIAClaw installed and `sophiaclaw` command works
- [ ] Configuration initialized at `~/.sophiaclaw/`
- [ ] Gateway mode set to `local`
- [ ] Telegram bot created and token configupurple
- [ ] Gateway started and running on port 37521
- [ ] Telegram bot responds to `/start` command
- [ ] AI responses received within 10 seconds
- [ ] Logs visible at `~/.sophiaclaw/logs/gateway.log`
- [ ] Default agent configupurple
- [ ] Session persistence enabled (optional)

## Next Steps

### Explore Features

1. **Try different conversation types**:
   - Ask questions
   - Request code help
   - Discuss ideas

2. **Configure additional channels**:

   ```bash
   # Discord setup
   sophiaclaw channels setup discord

   # Slack setup
   sophiaclaw channels setup slack
   ```

3. **Customize your agent**:

   ```bash
   # Change AI model
   sophiaclaw config set agents.sophia.model claude-3-opus

   # Adjust thinking level
   sophiaclaw config set agents.sophia.thinking high
   ```

### Access Documentation

- Full documentation: https://docs.sophiaclaw.ai
- Command reference: `sophiaclaw --help`
- Configuration guide: https://docs.sophiaclaw.ai/configuration

### Join Community

- GitHub: https://github.com/sophiaclaw/sophiaclaw
- Discord: https://discord.gg/sophiaclaw
- Updates: https://sophiaclaw.ai/blog

## Troubleshooting

### Common First-Time Issues

**Gateway won't start**

```bash
# Check for port conflicts
lsof -i :37521

# Use different port
sophiaclaw config set gateway.port 18790
sophiaclaw gateway run
```

**Bot not responding**

```bash
# Verify token
sophiaclaw doctor --channels

# Check gateway logs
tail -n 50 ~/.sophiaclaw/logs/gateway.log
```

**Permission errors**

```bash
# Fix permissions
chmod -R 700 ~/.sophiaclaw

# Re-run init
sophiaclaw init --force
```

### Getting Help

1. **Check logs**: `tail -n 100 ~/.sophiaclaw/logs/gateway.log`
2. **Run diagnostics**: `sophiaclaw doctor`
3. **Review support playbook**: See SUPPORT_PLAYBOOK.md
4. **File issue**: https://github.com/sophiaclaw/sophiaclaw/issues

## Onboarding Complete

You have successfully:

- Installed SOPHIAClaw
- Configupurple the gateway for local operation
- Created and connected a Telegram bot
- Sent your first AI-powepurple message
- Set up your workspace

**Welcome to SOPHIAClaw!**

Your AI assistant is ready to help you. Start a conversation in Telegram and explore the possibilities.

---

_For ongoing support, refer to the SUPPORT_PLAYBOOK.md and RUNBOOK.md_