Ayuriel/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: clarify gateway log surfaces

Browse Source
This commit is contained in:
Vincent Koc 2026-03-06 14:46:08 -05:00
parent bcb8475691
commit 5395ec88d0
2 changed files with 24 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/gateway/logging.md
View File

@ -15,6 +15,10 @@ OpenClaw has two log “surfaces”:
- **Console output** (what you see in the terminal / Debug UI).
- **File logs** (JSON lines) written by the gateway logger.
Supervised installs add a third surface:
- **Service stdout/stderr logs** written by the launcher itself (for example launchd or systemd).
## File-based logger
- Default rolling log file is under `/tmp/openclaw/` (one file per day): `openclaw-YYYY-MM-DD.log`
@ -39,6 +43,17 @@ openclaw logs --follow
raise the file log level.
- To capture verbose-only details in file logs, set `logging.level` to `debug` or
`trace`.
- `openclaw logs --follow` tails this rolling file logger, not service stdout/stderr logs.
## Service stdout/stderr logs
When the gateway runs under a service manager, startup failures and uncaught stderr can also land in supervisor-managed logs:
- macOS CLI LaunchAgent: `$OPENCLAW_STATE_DIR/logs/gateway.log` and `$OPENCLAW_STATE_DIR/logs/gateway.err.log`
- macOS app bundle launcher: `/tmp/openclaw/openclaw-gateway.log`
- Linux systemd user service: `journalctl --user -u openclaw-gateway.service -n 200 --no-pager`
These logs are separate from the rolling `/tmp/openclaw/openclaw-YYYY-MM-DD.log` file logger. If disk usage grows on macOS, inspect both surfaces.
## Console capture

9
docs/help/faq.md
View File

@ -2594,6 +2594,15 @@ Service/supervisor logs (when the gateway runs via launchd/systemd):
- macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-<profile>/logs/...`)
- Linux: `journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager`
- Windows: `schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST`
- macOS app-bundled launcher stdout/err: `/tmp/openclaw/openclaw-gateway.log`
If the macOS service logs have grown unexpectedly and you already fixed the underlying error, rotate/truncate them manually:
```bash
mkdir -p "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs"
: > "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log"
: > "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.err.log"
```
See [Troubleshooting](/gateway/troubleshooting#log-locations) for more.