Overview
Concrete platform-aware gateway service installer for the OpenClaw daemon, provided by resolveGatewayService and GatewayService.install in src/daemon/service.ts.
Description
resolveGatewayService is a factory function that detects the current operating system via process.platform and returns a GatewayService object implementing a uniform interface for managing the OpenClaw gateway as a background service. On macOS, it uses launchd (LaunchAgent plist files). On Linux, it uses systemd (user-level unit files). On Windows, it uses schtasks (Scheduled Tasks). The returned object exposes install, uninstall, stop, restart, isLoaded, readCommand, and readRuntime methods.
The install method accepts a GatewayServiceInstallArgs object specifying the program arguments (the command to run), environment variables, working directory, and output streams, then generates and registers the appropriate OS-level service descriptor.
Usage
Called during onboarding finalization (when the user opts to install the daemon) and by the openclaw daemon install / openclaw daemon uninstall CLI commands. Also used by openclaw status to check whether the gateway service is registered and running.
Code Reference
Source Location
- Repository: openclaw
- File:
src/daemon/service.ts
- Lines: 66-155 (resolveGatewayService); 30-37 (GatewayServiceInstallArgs type); 39-64 (GatewayService type)
Signature
export function resolveGatewayService(): GatewayService
// GatewayService.install method signature
install: (args: GatewayServiceInstallArgs) => Promise<void>
Import
import { resolveGatewayService } from "../daemon/service.js";
import type { GatewayService, GatewayServiceInstallArgs } from "../daemon/service.js";
I/O Contract
Inputs (resolveGatewayService)
| Name |
Type |
Required |
Description
|
| (none) |
-- |
-- |
Uses process.platform to detect the OS. Throws if the platform is not darwin, linux, or win32.
|
Outputs (resolveGatewayService)
| Name |
Type |
Description
|
| (return) |
GatewayService |
An object with methods: install, uninstall, stop, restart, isLoaded, readCommand, readRuntime, plus descriptive properties label, loadedText, notLoadedText.
|
Inputs (GatewayService.install)
| Name |
Type |
Required |
Description
|
| args.env |
undefined> |
Yes |
Environment variables for the child process execution context (e.g., PATH).
|
| args.stdout |
NodeJS.WritableStream |
Yes |
Stream for status output during installation.
|
| args.programArguments |
string[] |
Yes |
The full command array to execute (e.g., ["openclaw", "gateway", "run", "--port", "18789"]).
|
| args.workingDirectory |
string |
No |
The working directory for the service process.
|
| args.environment |
undefined> |
No |
Additional environment variables to set in the service descriptor.
|
| args.description |
string |
No |
Human-readable description for the service.
|
Outputs (GatewayService.install)
| Name |
Type |
Description
|
| (return) |
Promise<void> |
Resolves when the service has been successfully registered with the OS. Rejects if registration fails (e.g., invalid path, permission error).
|
Platform Implementations
macOS (darwin)
| Property |
Value
|
| label |
"LaunchAgent"
|
| loadedText |
"loaded"
|
| notLoadedText |
"not loaded"
|
| Backend |
launchd via launchctl -- writes a plist to ~/Library/LaunchAgents/
|
Linux
| Property |
Value
|
| label |
"systemd"
|
| loadedText |
"enabled"
|
| notLoadedText |
"disabled"
|
| Backend |
systemd user service -- writes a unit file to ~/.config/systemd/user/
|
Windows (win32)
| Property |
Value
|
| label |
"Scheduled Task"
|
| loadedText |
"registered"
|
| notLoadedText |
"missing"
|
| Backend |
schtasks -- registers a scheduled task triggered at logon
|
Usage Examples
Basic Usage
import { resolveGatewayService } from "../daemon/service.js";
const service = resolveGatewayService();
// Install the gateway as a background service
await service.install({
env: process.env,
stdout: process.stdout,
programArguments: [
"openclaw", "gateway", "run",
"--bind", "loopback",
"--port", "18789",
],
workingDirectory: "/home/user/openclaw",
description: "OpenClaw AI Gateway",
});
// Check if it is running
const loaded = await service.isLoaded({ env: process.env });
console.log(`Service ${service.label}: ${loaded ? service.loadedText : service.notLoadedText}`);
Reading Service Runtime Status
import { resolveGatewayService } from "../daemon/service.js";
const service = resolveGatewayService();
const runtime = await service.readRuntime(process.env);
console.log(`Status: ${runtime.status}, PID: ${runtime.pid}`);
Key Dependencies
| Dependency |
Purpose
|
| node:child_process |
Executes launchctl, systemctl, and schtasks commands for each platform
|
| src/daemon/launchd.js |
macOS LaunchAgent plist generation and launchctl wrappers
|
| src/daemon/systemd.js |
Linux systemd unit file generation and systemctl wrappers
|
| src/daemon/schtasks.js |
Windows Scheduled Task XML generation and schtasks wrappers
|
| src/daemon/service-runtime.js |
GatewayServiceRuntime type for runtime status reporting
|
Related Pages
Implements Principle
