OmniClaw Setup

Read the user's request first. Most requests are lightweight — handle them directly without loading any guide.

Route by intent

Reboot service

Check status first, then act.

bash
1# 1. Which agents are registered?
2sqlite3 store/messages.db "SELECT folder, name FROM registered_groups"
3
4# 2. Is the service running? (pick one)
5launchctl list | grep omniclaw          # macOS
6systemctl --user status omniclaw        # Linux
7
8# 3. Check for running agent containers
9launchctl list | grep 'container-runtime-linux.omniclaw'   # macOS
10# Each line = an active agent container processing a task or message
11
12# 4. Recent activity per agent
13for folder in $(sqlite3 store/messages.db "SELECT folder FROM registered_groups"); do
14  LATEST=$(ls -t "groups/$folder/logs/" 2>/dev/null | head -1)
15  [ -n "$LATEST" ] && echo "$folder: $(echo "$LATEST" | sed 's/container-//;s/\.log//')" || echo "$folder: no activity"
16done
17
18# 5. Recent errors
19tail -20 logs/omniclaw.log

Present agent status to user and ask which to reboot (all vs specific). Use AskUserQuestion.

Drain active containers before restarting

IMPORTANT: If any agent containers are running (step 3 above), you MUST wait for them to finish before restarting. Killing the orchestrator while containers are active destroys in-progress agent work.

Wait for containers to drain:

bash
1# Poll until no omniclaw containers remain (check every 10s, timeout after 10min)
2echo "Waiting for active containers to finish..."
3for i in $(seq 1 60); do
4  ACTIVE=$(launchctl list 2>/dev/null | grep -c 'container-runtime-linux.omniclaw' || true)
5  [ "$ACTIVE" -eq 0 ] && echo "All containers finished." && break
6  echo "  $ACTIVE container(s) still running... (${i}0s elapsed)"
7  sleep 10
8done

If the user explicitly says to restart immediately (e.g. "force restart", "restart now"), skip the drain wait. Otherwise always drain first.

Reboot all — macOS:

bash
1launchctl kickstart -k gui/$(id -u)/com.omniclaw
2sleep 3 && launchctl list | grep omniclaw
3tail -5 logs/omniclaw.log

Reboot all — Linux:

bash
1systemctl --user restart omniclaw
2sleep 3 && systemctl --user is-active omniclaw
3tail -5 logs/omniclaw.log

Report whether the service came back up successfully.

Linger fix

Linux only. If user reports agents going offline after SSH disconnect:

bash
1# Check
2loginctl show-user $(whoami) | grep Linger
3
4# Fix
5loginctl enable-linger $(whoami)
6
7# Verify
8loginctl show-user $(whoami) | grep Linger
9# Should show Linger=yes

Without linger, systemd tears down all user services when the last session ends. This is also handled automatically by step 10 (08-setup-service.sh) during fresh install.

Verify

bash
1./.claude/skills/setup/scripts/09-verify.sh

Fix any failures per guides/troubleshooting.md.

OpenCode auth reset

Use this when a local OpenCode agent creates fresh sessions but still returns empty assistant outputs, especially after auth/provider drift.

Common symptom:

text
1[opencode-runtime] Created new session: ...
2[opencode-runtime] Injected system context
3[opencode-runtime] extractResponseText: 0 parts, types:

Known cause:

• base OpenCode auth store for the agent contains mixed providers or stale auth state
• fresh dispatch sessions inherit that bad base state

Safe reset sequence for a local agent such as ocpeyton-discord:

bash
1# Stop service first
2launchctl bootout gui/$(id -u)/com.omniclaw          # macOS
3systemctl --user stop omniclaw                       # Linux
4
5# Clear persisted dispatch sessions
6sqlite3 store/messages.db "DELETE FROM sessions WHERE group_folder LIKE 'ocpeyton-discord__dispatch__%';"
7
8# Clear dispatch runtime stores
9find data/opencode-data -maxdepth 1 -type d -name 'ocpeyton-discord__dispatch__*' -exec rm -rf {} +
10
11# Clear base auth/database so agent rebuilds from fresh login
12rm -f data/opencode-data/ocpeyton-discord/auth.json \
13      data/opencode-data/ocpeyton-discord/mcp-auth.json \
14      data/opencode-data/ocpeyton-discord/opencode.db \
15      data/opencode-data/ocpeyton-discord/opencode.db-shm \
16      data/opencode-data/ocpeyton-discord/opencode.db-wal
17
18# Start service again
19launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.omniclaw.plist   # macOS
20systemctl --user start omniclaw                                              # Linux

After restart:

• re-auth if needed
• send a simple test message to the agent
• confirm the next run no longer logs extractResponseText: 0 parts