Troubleshooting

Common issues when running OpenClaw in a sandbox.

Gateway Won't Start

Symptom: openclaw gateway fails with "port already in use" or "already running"

Fix: Kill the old process and restart:

pkill -f openclaw-gateway
sleep 2
nohup openclaw gateway > ~/.openclaw/logs/gateway-sandbox.log 2>&1 &

Verify:

tail -10 ~/.openclaw/logs/gateway-sandbox.log

You should see ws client ready if a channel (Feishu/Discord) is configured.

Gateway Running but Bot Doesn't Reply

Symptom: Gateway logs show ws client ready but no messages arrive from Feishu/Discord.

Check channel status:

openclaw channels status --json

Look at lastInboundAt — if it's null, no messages have ever been received.

Common causes:

Model Auth Errors

Symptom: No API key found for provider "anthropic" or "openai-codex"

Check:

openclaw models status --json

What you want:

• defaultModel is set (e.g., openai-codex/gpt-5.4)
• missingProvidersInUse is empty
• providersWithOAuth shows your provider

Fix: See Model Auth for setup commands.

Common mistake: Setting the auth profile fields individually instead of as a JSON object:

# WRONG — fails validation because provider and mode must be set together
openclaw config set auth.profiles.openai-codex:default.provider openai-codex
openclaw config set auth.profiles.openai-codex:default.mode oauth

# RIGHT — set as one JSON object
openclaw config set auth.profiles.openai-codex:default '{"provider":"openai-codex","mode":"oauth"}' --json

cue: command not found

Symptom: cue is not found in the terminal after bootstrap.

Check if installed:

ls ~/.cue/bin/cue 2>/dev/null || ls /usr/local/bin/cue 2>/dev/null || echo "Not installed"

If installed but not in PATH:

export PATH="$HOME/.cue/bin:$PATH"
cue --version

To make it permanent:

echo 'export PATH="$HOME/.cue/bin:$PATH"' >> ~/.bashrc

If not installed: Run bootstrap from the sandbox API or install manually:

curl -fsSL https://cueosai.sfo3.digitaloceanspaces.com/cue-cli/dev/latest.tgz | \
  tar xz --strip-components=1 -C ~/.cue/lib/cue-cli
mkdir -p ~/.cue/bin
ln -sf ~/.cue/lib/cue-cli/bin/cue.js ~/.cue/bin/cue
chmod +x ~/.cue/bin/cue ~/.cue/lib/cue-cli/dist/cli.mjs

Updating the CLI

Self-update from the sandbox terminal:

cue update

This fetches the latest tarball from S3 and re-extracts in place. No sudo needed.

Gateway Doesn't Pick Up New CLI

Symptom: After cue update, the gateway still uses the old CLI version.

Fix: Restart the gateway:

pkill -f openclaw-gateway
sleep 2
nohup openclaw gateway > ~/.openclaw/logs/gateway-sandbox.log 2>&1 &

The gateway spawns agent processes using the cue binary from PATH. Restarting makes it pick up the updated version.

Stale Processes After Bootstrap

Symptom: Bootstrap says success but nothing works because old processes are still running.

Fix: Kill all old processes:

pkill -f openclaw
pkill -f cue

Then restart what you need:

# Restart gateway
nohup openclaw gateway > ~/.openclaw/logs/gateway-sandbox.log 2>&1 &

# Restart cue manager (if needed)
cue --manager start

Checking Logs

Remote Debug via API

If you can't access the terminal, use the sandbox execute API:

TOKEN="<user-access-token>"
SANDBOX_ID="<sandbox-id>"

curl -s "https://api.cueos.ai/api/v1/sandboxes/$SANDBOX_ID/execute" \
  -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "openclaw channels status --json 2>&1"}'

To get a user token via admin API, see the Sandbox Debug Guide in the backend docs.