OpenClaw-Setup/openclaw-setup-max/docs/operations/troubleshooting.md

OpenClaw + Ollama Troubleshooting (macOS)

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

Quick Health Check

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 /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

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

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):

openclaw models set ollama/qwen3:14b

2. Missing Ollama auth in runtime env:

export OLLAMA_API_KEY="ollama-local"
openclaw gateway run --force

3. Pairing not approved:

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

# 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.

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:

/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:

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:

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:

openclaw hooks info boot-md

If workspace changes:

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:

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.