docs: Add comprehensive FAQ for common issues#312
docs: Add comprehensive FAQ for common issues#312vincent067 wants to merge 1 commit intoabhi1693:masterfrom
Conversation
…ing index Add a new FAQ document covering common setup, configuration, and usage questions for OpenClaw Mission Control. The FAQ addresses issues seen in recent GitHub issues including: - Gateway connection problems (abhi1693#298, abhi1693#296) - Authentication and token issues - Board onboarding stuck (abhi1693#293) - Agent offline troubleshooting - Performance and scaling questions - Docker-specific configuration Also update the troubleshooting README to provide a quick reference table and better navigation to the detailed guides. The FAQ is organized by topic with clear symptoms, solutions, and command examples to help users self-diagnose and fix common issues. Tested: Documentation renders correctly in Markdown viewers. Related issues: abhi1693#298, abhi1693#296, abhi1693#293, abhi1693#304
There was a problem hiding this comment.
Pull request overview
Adds a new troubleshooting FAQ to the documentation to help users resolve common setup/connectivity/auth/worker issues when running OpenClaw Mission Control, and updates the troubleshooting index to improve navigation.
Changes:
- Introduces
docs/troubleshooting/faq.mdwith common issues, checklists, and operational tips. - Updates
docs/troubleshooting/README.mdto link the FAQ and add a quick-reference table.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/troubleshooting/faq.md | New comprehensive FAQ covering setup, gateway connectivity, auth, worker/redis checks, and scaling/backups. |
| docs/troubleshooting/README.md | Reworks troubleshooting index with links and a quick-fixes table for faster triage. |
| 1. **Check your token**: | ||
| ```bash | ||
| # Test your token | ||
| curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/health |
There was a problem hiding this comment.
/api/v1/health does not appear to be a valid endpoint in this repo (service health endpoints are /health and /healthz, and the authenticated user bootstrap endpoint is /api/v1/auth/bootstrap). This curl example will 404, so readers won’t be able to validate their token as written.
| curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/health | |
| curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/auth/bootstrap |
| # You should see: backend, frontend, db, redis, worker | ||
| ``` | ||
|
|
||
| 2. **Check worker logs**: | ||
| ```bash | ||
| docker compose logs -f worker |
There was a problem hiding this comment.
The compose service is named webhook-worker (see compose.yml), not worker. As written, this checklist will confuse users because docker compose logs -f worker won’t work and docker compose ps won’t show a worker service.
| # You should see: backend, frontend, db, redis, worker | |
| ``` | |
| 2. **Check worker logs**: | |
| ```bash | |
| docker compose logs -f worker | |
| # You should see: backend, frontend, db, redis, webhook-worker |
- Check worker logs:
docker compose logs -f webhook-worker
There was a problem hiding this comment.
You should also add worker container to docker compose since it's not yet added.
| 3. **Redis connectivity**: | ||
| ```bash | ||
| # Verify Redis is accessible | ||
| docker compose exec backend redis-cli -h redis ping |
There was a problem hiding this comment.
redis-cli isn’t installed in the backend image (Dockerfile only installs curl/ca-certificates/git), so docker compose exec backend redis-cli ... will fail. Use docker compose exec redis redis-cli ping (or equivalent) to validate Redis connectivity.
| docker compose exec backend redis-cli -h redis ping | |
| docker compose exec redis redis-cli ping |
| 1. **Check the agent provisioning flow**: | ||
| ```bash | ||
| # View logs | ||
| docker compose logs -f worker | grep lifecycle | ||
| ``` |
There was a problem hiding this comment.
This references docker compose logs -f worker, but the service is named webhook-worker in compose.yml. The command will fail as written.
|
|
||
| 4. **Worker scaling**: For high task volume, you can run multiple workers: | ||
| ```bash | ||
| docker compose up -d --scale worker=3 |
There was a problem hiding this comment.
docker compose up -d --scale worker=3 won’t work with the current compose file because the worker service is named webhook-worker. Update the example to scale the correct service.
| docker compose up -d --scale worker=3 | |
| docker compose up -d --scale webhook-worker=3 |
abhi1693
left a comment
abhi1693
left a comment
There was a problem hiding this comment.
Nice work this documentation. I think if you can check the issues raised by copilot and add the worker container that you have mentioned in your docs, this is good to be merged
Hi @abhi1693! 👋
I've put together a comprehensive FAQ document based on the common issues I've seen in the GitHub issues and my own experience setting up Mission Control.
What's included
New FAQ (
docs/troubleshooting/faq.md)Updated Troubleshooting Index
Issues addressed
This FAQ should help users with:
execcommand permission #304 - exec command permission issuesTesting
Let me know if you'd like any changes! Happy to iterate on this. 🙏
Type: Documentation improvement
Breaking changes: None