mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-10 23:30:53 +08:00
oliver
dbbe3add6a
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
75 lines
2.1 KiB
Markdown
75 lines
2.1 KiB
Markdown
---
|
||
summary: "Gateway runtime on macOS (external launchd service)"
|
||
read_when:
|
||
- Packaging OpenClaw.app
|
||
- Debugging the macOS gateway launchd service
|
||
- Installing the gateway CLI for macOS
|
||
title: "Gateway on macOS"
|
||
---
|
||
|
||
# Gateway on macOS (external launchd)
|
||
|
||
OpenClaw.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
|
||
expects an **external** `openclaw` CLI install, does not spawn the Gateway as a
|
||
child process, and manages a per‑user launchd service to keep the Gateway
|
||
running (or attaches to an existing local Gateway if one is already running).
|
||
|
||
## Install the CLI (required for local mode)
|
||
|
||
Node 24 is the default runtime on the Mac. Node 22 LTS, currently `22.14+`, still works for compatibility. Then install `openclaw` globally:
|
||
|
||
```bash
|
||
npm install -g openclaw@<version>
|
||
```
|
||
|
||
The macOS app’s **Install CLI** button runs the same global install flow the app
|
||
uses internally: it prefers npm first, then pnpm, then bun if that is the only
|
||
detected package manager. Node remains the recommended Gateway runtime.
|
||
|
||
## Launchd (Gateway as LaunchAgent)
|
||
|
||
Label:
|
||
|
||
- `ai.openclaw.gateway` (or `ai.openclaw.<profile>`; legacy `com.openclaw.*` may remain)
|
||
|
||
Plist location (per‑user):
|
||
|
||
- `~/Library/LaunchAgents/ai.openclaw.gateway.plist`
|
||
(or `~/Library/LaunchAgents/ai.openclaw.<profile>.plist`)
|
||
|
||
Manager:
|
||
|
||
- The macOS app owns LaunchAgent install/update in Local mode.
|
||
- The CLI can also install it: `openclaw gateway install`.
|
||
|
||
Behavior:
|
||
|
||
- “OpenClaw Active” enables/disables the LaunchAgent.
|
||
- App quit does **not** stop the gateway (launchd keeps it alive).
|
||
- If a Gateway is already running on the configured port, the app attaches to
|
||
it instead of starting a new one.
|
||
|
||
Logging:
|
||
|
||
- launchd stdout/err: `/tmp/openclaw/openclaw-gateway.log`
|
||
|
||
## Version compatibility
|
||
|
||
The macOS app checks the gateway version against its own version. If they’re
|
||
incompatible, update the global CLI to match the app version.
|
||
|
||
## Smoke check
|
||
|
||
```bash
|
||
openclaw --version
|
||
|
||
OPENCLAW_SKIP_CHANNELS=1 \
|
||
OPENCLAW_SKIP_CANVAS_HOST=1 \
|
||
openclaw gateway --port 18999 --bind loopback
|
||
```
|
||
|
||
Then:
|
||
|
||
```bash
|
||
openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000
|
||
```
|