aceeb7b542
- ansible/: VM provisioning playbooks and roles - provision-vm.yml: create KVM VM from Ubuntu cloud image - install.yml: install OpenClaw on guest (upstream) - customize.yml: swappiness, virtiofs fstab, linger - roles/vm/: libvirt domain XML, cloud-init templates - inventory.yml + host_vars/zap.yml: zap instance config - backup-openclaw-vm.sh: daily rsync + MinIO upload - restore-openclaw-vm.sh: full redeploy from scratch - README.md: full operational documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
161 lines
3.1 KiB
Markdown
161 lines
3.1 KiB
Markdown
---
|
|
title: Troubleshooting
|
|
description: Common issues and solutions
|
|
---
|
|
|
|
# Troubleshooting
|
|
|
|
## Container Can't Reach Internet
|
|
|
|
**Symptom**: OpenClaw can't connect to WhatsApp/Telegram
|
|
|
|
**Check**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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):
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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.
|
|
|
|
```ini
|
|
[defaults]
|
|
pipelining = True
|
|
```
|
|
|
|
Alternatively, if you cannot use pipelining, you can allow world-readable temporary files (less secure):
|
|
```ini
|
|
[defaults]
|
|
allow_world_readable_tmpfiles = True
|
|
```
|
|
|
|
### Collection missing
|
|
...
|
|
```bash
|
|
ansible-galaxy collection install -r requirements.yml
|
|
```
|
|
|
|
**Permission denied**:
|
|
```bash
|
|
# Run with --ask-become-pass
|
|
ansible-playbook playbook.yml --ask-become-pass
|
|
```
|
|
|
|
**Docker daemon not running**:
|
|
```bash
|
|
sudo systemctl start docker
|
|
# Re-run playbook
|
|
```
|