TOOLS.md - Environment & Tool Notes

# TOOLS.md - Environment & Tool Notes

## Infrastructure

### Droplet
- **Host:** openclaw29onubuntu-s-2vcpu-4gb-120gb-intel-tor1-01
- **IP:** (check DigitalOcean console)
- **OS:** Ubuntu with Docker

### Database
- **Type:** DigitalOcean Managed PostgreSQL
- **Host:** openclaw-knowledge-db-do-user-8736740-0.e.db.ondigitalocean.com
- **Port:** 25060
- **Database:** openclaw_kb
- **Note:** Port 25060 often blocked by ISPs — access from droplet

### Scripts Location
- **Path:** /opt/zoho-extract/
- **Venv:** /opt/zoho-extract/venv/
- **Activate:** `cd /opt/zoho-extract && source venv/bin/activate`

### Backups
- **Local:** /backups/
- **GitHub:** github.com/t7qgtqzrst-blip/openclaw-workspace-
- **Cron:** Daily at 2 AM

---

## Zoho API

### Endpoints
- **Auth:** accounts.zoho.com
- **CRM:** www.zohoapis.com/crm/v2/
- **SalesIQ:** salesiq.zoho.com/api/v2/rollerup/
- **Books:** books.zoho.com/api/v3/
- **WorkDrive:** workdrive.zoho.com (not zohoapis.com!)

### Tokens
- **Main token:** CRM, Books, Desk, Mail, Connect, WorkDrive
- **SalesIQ token:** Separate (different scopes)

### Rate Limits
- CRM: 100 requests/minute
- Add `time.sleep(0.1)` between requests

---

## OpenAI API

### Embedding Model
- **Model:** text-embedding-3-small
- **Dimensions:** 1536
- **Cost:** ~$0.02 per million tokens

---

## Common Commands

### Check running jobs
```bash
ps aux | grep python
```

### Check email extraction progress
```bash
python3 -c "import os, psycopg2; from dotenv import load_dotenv; load_dotenv('/opt/zoho-extract/.env'); conn = psycopg2.connect(host=os.getenv('DB_HOST'), port=os.getenv('DB_PORT'), dbname=os.getenv('DB_NAME'), user=os.getenv('DB_USER'), password=os.getenv('DB_PASSWORD'), sslmode='require'); cur = conn.cursor(); cur.execute('SELECT COUNT(*) FROM zoho.crm_emails WHERE content IS NOT NULL'); print(f'Emails: {cur.fetchone()[0]}/42227')"
```

### Run backup manually
```bash
/opt/zoho-extract/backup.sh
```

### Push workspace to GitHub
```bash
cd /home/openclaw/.openclaw/workspace
git add -A && git commit -m "Update" && git push
```

### Tail background job log
```bash
tail -f /opt/zoho-extract/email_extraction.log
```

---

## Database Schemas

### zoho (22 tables)
- crm_contacts, crm_leads, crm_accounts, crm_deals
- crm_notes, crm_activities, crm_cases, crm_emails
- books_contacts, books_invoices, books_estimates, books_payments
- salesiq_chats, workdrive_files, workdrive_folders
- mail_accounts, mail_messages, desk_tickets, etc.

### kb (3 tables)
- articles, categories, document_chunks (with embeddings)

### justcall (3 tables)
- calls, sms, contacts

---

## OpenClaw Gateway

### Environment Facts (DigitalOcean Marketplace Install)
- **Droplet IP:** 68.183.198.0
- **Gateway port:** 18789
- **Reverse proxy:** Caddy (NOT nginx), config at `/etc/caddy/Caddyfile`
- **System service:** `/etc/systemd/system/openclaw.service` (runs as `openclaw` user)
- **Anthropic key:** `/opt/openclaw.env`
- **Active config:** `/root/.openclaw/openclaw.json`
- **Legacy config:** `/home/openclaw/.openclaw/` (DON'T USE)
- **Working venv:** `/opt/zoho-extract/venv`

### Browser Access URL
```
https://68.183.198.0/__openclaw__/?token=YOUR_TOKEN
```
Token is in `/root/.openclaw/openclaw.json` under `gateway → auth → token`.

### The Correct Way To Start Gateway
```bash
cd /opt/zoho-extract
source venv/bin/activate
openclaw gateway &
```

### ⚠️ NEVER DO THESE THINGS
1. **Never run `openclaw doctor --fix`** — installs conflicting user-level systemd service
2. **Never run `chown -R openclaw` on `/root/.openclaw/`** — breaks permissions
3. **Never start gateway manually while systemd service is enabled**
4. **Never run `openclaw gateway` while system service is active**

### Gateway Settings (DON'T CHANGE without good reason)
```json
"gateway": {
  "mode": "local",
  "bind": "lan",
  "controlUi": {
    "dangerouslyDisableDeviceAuth": true
  },
  "auth": {
    "token": "..."
  }
}
```

### If Gateway Gets Stuck (Nuclear Option)
```bash
# Stop ALL services
systemctl stop openclaw.service
systemctl disable openclaw.service
systemctl --user stop openclaw-gateway.service
systemctl --user disable openclaw-gateway.service
pkill -9 -f openclaw-gateway
sleep 3

# Restart clean
cd /opt/zoho-extract && source venv/bin/activate
openclaw gateway &
```

### Why Things Break
- `openclaw doctor --fix` installs a user-level systemd service that fights with the marketplace system service
- System service has `Restart=always` — killing the process just respawns it
- Anthropic API key in `/opt/openclaw.env` isn't loaded by systemd services automatically
- Two gateway instances = constant conflicts
- Two config locations (`/root/.openclaw/` vs `/home/openclaw/.openclaw/`) cause confusion

### Quick Troubleshooting
```bash
# Check what's running
ps aux | grep openclaw
systemctl status openclaw.service

# View logs
tail -50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# Check which config is active
openclaw config --path
```

---

## Notes
- Always sanitize JSON before PostgreSQL (remove `\x00`)
- Use `nohup command > log 2>&1 &` for background jobs
- Check `git config --global --add safe.directory` if git fails as root
- **Don't change OpenClaw core gateway configs without understanding the full chain (Caddy → Gateway → Browser)**