Skip to content

troubleshooting.md

Latest commit

 

History

History
160 lines (118 loc) · 3.11 KB

troubleshooting.md

File metadata and controls

160 lines (118 loc) · 3.11 KB
Raw
title Troubleshooting
description Common issues and solutions

Troubleshooting

Container Can't Reach Internet

Symptom: OpenClaw can't connect to WhatsApp/Telegram

Check:

# Test from container
sudo docker exec openclaw ping -c 3 8.8.8.8

# Check UFW allows outbound
sudo ufw status verbose | grep OUT

Solution:

# Verify DOCKER-USER allows established connections
sudo iptables -L DOCKER-USER -n -v

# Restart Docker + Firewall
sudo systemctl restart docker
sudo ufw reload
sudo systemctl restart openclaw

Port Already in Use

Symptom: Port 3000 conflict

Solution:

# Find what's using port 3000
sudo ss -tlnp | grep 3000

# Change OpenClaw port
sudo nano /opt/openclaw/docker-compose.yml
# Change: "127.0.0.1:3001:3000"

sudo systemctl restart openclaw

Firewall Lockout

Symptom: Can't SSH after installation

Solution (via console/rescue mode):

# Disable UFW temporarily
sudo ufw disable

# Check SSH rule exists
sudo ufw status numbered

# Re-add SSH rule
sudo ufw allow 22/tcp

# Re-enable
sudo ufw enable

Container Won't Start

Check logs:

# Systemd logs
sudo journalctl -u openclaw -n 50

# Docker logs
sudo docker logs openclaw

# Compose status
sudo docker compose -f /opt/openclaw/docker-compose.yml ps

Common fixes:

# Rebuild image
cd /opt/openclaw
sudo docker compose build --no-cache
sudo systemctl restart openclaw

# Check permissions
sudo chown -R openclaw:openclaw /home/openclaw/.openclaw

Verify Docker Isolation

Test that external ports are blocked:

# Start test container
sudo docker run -d -p 80:80 --name test-nginx nginx

# From EXTERNAL machine (should fail):
curl http://YOUR_SERVER_IP:80

# From SERVER (should work):
curl http://localhost:80

# Cleanup
sudo docker rm -f test-nginx

UFW Status Shows Inactive

Fix:

# Enable UFW
sudo ufw enable

# Reload rules
sudo ufw reload

# Verify
sudo ufw status verbose

Ansible Playbook Fails

Failed to set permissions on temporary files (Become Issue)

Symptom: fatal: [host]: FAILED! => {"msg": "Failed to set permissions on the temporary files Ansible needs to create when becoming an unprivileged user..."}

Cause: This happens when connecting as an unprivileged user (e.g., ansible) and using become_user to switch to another unprivileged user (e.g., openclaw). Ansible struggles to share temporary module files between them if the filesystem doesn't support POSIX ACLs.

Solution: Enable Ansible Pipelining in your ansible.cfg. This executes modules via stdin without creating temporary files.

[defaults]
pipelining = True

Alternatively, if you cannot use pipelining, you can allow world-readable temporary files (less secure):

[defaults]
allow_world_readable_tmpfiles = True

Collection missing

...

ansible-galaxy collection install -r requirements.yml

Permission denied:

# Run with --ask-become-pass
ansible-playbook playbook.yml --ask-become-pass

Docker daemon not running:

sudo systemctl start docker
# Re-run playbook