# OpenClaw + Ollama Troubleshooting (macOS)

This file captures the exact issues we hit on this machine and the fixes that worked.

## Quick Health Check

```bash
openclaw status --deep
openclaw gateway health --json
ollama list
```

## 1) `Operation not permitted` on `/Volumes/Data/openclaw-setups/openclaw-setup-max`

### Symptoms
- `ls: /Volumes/Data/openclaw-setups/openclaw-setup-max: Operation not permitted`
- `bash setup/setup_openclaw_ollama.sh: Operation not permitted`

### Cause
- macOS TCC privacy restrictions for Terminal on external/removable volumes.

### Fix
1. In macOS Settings, grant terminal app access:
   - Privacy & Security -> Files and Folders -> Terminal -> Removable Volumes ON
   - Privacy & Security -> Full Disk Access -> Terminal ON
2. Restart Terminal.
3. Run script with `bash`:

```bash
bash /Volumes/Data/openclaw-setups/openclaw-setup-max/setup/setup_openclaw_ollama.sh
```

## 2) OpenClaw install failed with `env: npm: No such file or directory`

### Cause
- Broken Homebrew `npm` symlink.

### Fix

```bash
brew reinstall node
node -v
npm -v
```

## 3) Telegram connected but no bot reply

### Symptoms
- Telegram channel shows configured, but bot does not respond to prompts.
- Logs show agent run started but no final answer.

### Checks

```bash
openclaw channels logs --channel telegram
openclaw logs --follow
openclaw pairing list telegram
```

### Common causes and fixes
1. Model lacks tool support (example: `deepseek-coder-v2:16b`):
```bash
openclaw models set ollama/qwen3:14b
```
2. Missing Ollama auth in runtime env:
```bash
export OLLAMA_API_KEY="ollama-local"
openclaw gateway run --force
```
3. Pairing not approved:
```bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```

## 4) Gateway timeout / closed connection errors

### Symptoms
- `gateway timeout after 10000ms`
- `gateway closed (1006 abnormal closure)`
- Port appears in-use but gateway is not responsive.

### Cause
- Stale/suspended OpenClaw process holding lock state.
- LaunchAgent using outdated gateway command.

### Recovery

```bash
# Remove stale local processes
pkill -f openclaw-gateway 2>/dev/null || true
pkill -f 'openclaw gateway' 2>/dev/null || true

# Verify port
lsof -nP -iTCP:18789 -sTCP:LISTEN

# Start clean in foreground
export OLLAMA_API_KEY="ollama-local"
openclaw gateway run --force
```

## 5) LaunchAgent service not staying up

### Symptoms
- `openclaw gateway status` shows loaded but not running.
- Launchd reports exit code `78: EX_CONFIG`.

### Fix that worked
- Preferred: run the upgrade workflow, which self-heals LaunchAgent + guards.
- `update_openclaw.sh` prints timestamped logs so restart timing is visible during the run.

```bash
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/update_openclaw.sh
```

- Manual fallback:
  1. Keep LaunchAgent logs in `/tmp` (avoids external-volume symlink path issues).
  2. Reinstall and restart the gateway service.

File:
- `~/Library/LaunchAgents/ai.openclaw.gateway.plist`

Set log paths:
```bash
/usr/libexec/PlistBuddy -c "Set :StandardOutPath /tmp/openclaw-gateway.launchd.log" ~/Library/LaunchAgents/ai.openclaw.gateway.plist
/usr/libexec/PlistBuddy -c "Set :StandardErrorPath /tmp/openclaw-gateway.launchd.err.log" ~/Library/LaunchAgents/ai.openclaw.gateway.plist
```

Reload service:
```bash
openclaw gateway install --force
launchctl bootout gui/$(id -u)/ai.openclaw.gateway 2>/dev/null || true
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
```

Verify:
```bash
launchctl print gui/$(id -u)/ai.openclaw.gateway | rg 'state =|last exit code|runs ='
openclaw gateway status
openclaw gateway health --json
ls -lT /tmp/openclaw-gateway.launchd.log /tmp/openclaw-gateway.launchd.err.log
```

## 6) docs/context/BOOT.md hook setup

Workspace boot file:
- `/Volumes/Data/openclaw-setups/openclaw-setup-max/docs/context/BOOT.md`

Hook verify:
```bash
openclaw hooks info boot-md
```

If workspace changes:
```bash
openclaw config set agents.defaults.workspace /Volumes/Data/openclaw-setups/openclaw-setup-max
```

## 7) Recommended local model defaults

Good local defaults for this machine:
- `ollama/qwen3:14b` (fastest stable)
- `ollama/devstral:24b` (better coding quality, slower)

Set default:
```bash
openclaw models set ollama/qwen3:14b
```

## 8) Security cleanup after setup

Rotate secrets if they were ever visible in logs/screens:
1. Telegram bot token (via `@BotFather`)
2. OpenClaw gateway token

Then restart gateway.