macOS LaunchAgent + SQLite：补齐 TMPDIR 避免 SQLITE_CANTOPEN
问题/场景：通过 launchd 启动网关时缺少 TMPDIR，SQLite 无法创建临时/WAL 文件导致启动失败。前置条件：macOS 且以 `openclaw gateway install` 方式注册 LaunchAgent。实施步骤：在服务环境中显式注入 TMPDIR → 重新加载 LaunchAgent → 观察数据库初始化日志。关键命令：openclaw gateway restart。验证：重启后不再出现 SQLITE_CANTOPEN。风险：TMPDIR 指向不可写目录仍会失败。来源：PR #20512。
GITHUBDiscovered 2026-02-19Author Clawborn
Prerequisites
- Gateway is managed by macOS launchd (LaunchAgent), not only interactive shell.
- You can inspect service env and logs for SQLite startup errors.
Steps
- Detect startup failures containing `SQLITE_CANTOPEN` while launchd-managed gateway boots.
- Ensure service env construction includes `TMPDIR` in addition to HOME/PATH.
- Reload or restart LaunchAgent and observe database initialization path and WAL creation.
- Keep TMPDIR writable and user-scoped (e.g., `/var/folders/...`) for persistent reliability.
Commands
openclaw gateway statusopenclaw gateway restartVerify
Gateway starts under LaunchAgent without database open errors and can process requests normally.
Caveats
- This fix is macOS launchd-specific; Linux systemd services require their own env checks.
- If temp directory cleanup policy is aggressive, intermittent DB issues may still occur（需验证）.
Source attribution
This tip is aggregated from community/public sources and preserved with attribution.
Open original source ↗