From ef31a333f79696781d17ddf08479204c663e0984 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 27 Apr 2026 03:29:55 +0100 Subject: [PATCH] docs: add gateway wrapper install examples --- CHANGELOG.md | 2 +- docs/cli/gateway.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c1aa6de223..eccfe3fad68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ Docs: https://docs.openclaw.ai ### Fixes - Cron: classify isolated runs as errors when final output narrates known execution-denial markers such as `SYSTEM_RUN_DENIED`, `INVALID_REQUEST`, or approval-binding refusal phrases, so blocked commands no longer appear green in cron history. Fixes #67172; carries forward #67186. Thanks @oc-gh-dr, @hclsys, and @1yihui. -- Gateway/install: add a validated `--wrapper`/`OPENCLAW_WRAPPER` service install path that persists executable LaunchAgent/systemd wrappers across forced reinstalls, updates, and doctor repairs instead of falling back to raw node/bun `ProgramArguments`. Fixes #69400. Thanks @willtmc. +- Gateway/install: add a validated `--wrapper`/`OPENCLAW_WRAPPER` service install path that persists executable LaunchAgent/systemd wrappers across forced reinstalls, updates, and doctor repairs instead of falling back to raw node/bun `ProgramArguments`. Fixes #69400. (#72445) Thanks @willtmc. - macOS Gateway: write launchd services with a state-dir `WorkingDirectory`, use a durable state-dir temp path instead of freezing macOS session `TMPDIR`, create that temp directory before bootstrap, and label abort-shaped launchd exits as `SIGABRT/abort` in status output. Fixes #53679 and #70223; refs #71848. Thanks @dlturock, @stammi922, and @palladius. - Exec approvals: accept runtime-owned `source: "allow-always"` and `commandText` allowlist metadata in gateway and node approval-set payloads so Control UI round-trips no longer fail with `unexpected property 'source'`. Fixes #60000; carries forward #60064. Thanks @sd1471123, @sharkqwy, and @luoyanglang. - Exec/node: skip approval-plan preparation for full-trust `host=node` runs so interpreter and script commands no longer fail with `SYSTEM_RUN_DENIED: approval cannot safely bind` when effective policy is `security=full` and `ask=off`. Fixes #48457 and duplicate #69251. Thanks @ajtran303, @jaserNo1, @Blakeshannon, @lesliefag, and @AvIsBeastMC. diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index a55cd1dbbe5..7322e2f5f81 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -422,6 +422,41 @@ openclaw gateway restart openclaw gateway uninstall ``` +### Install with a wrapper + +Use `--wrapper` when the managed service must start through another executable, for example a +secrets manager shim or a run-as helper. The wrapper receives the normal Gateway args and is +responsible for eventually exec'ing `openclaw` or Node with those args. + +```bash +cat > ~/.local/bin/openclaw-doppler <<'EOF' +#!/usr/bin/env bash +set -euo pipefail +exec doppler run --project my-project --config production -- openclaw "$@" +EOF +chmod +x ~/.local/bin/openclaw-doppler + +openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force +openclaw gateway restart +``` + +You can also set the wrapper through the environment. `gateway install` validates that the path is +an executable file, writes the wrapper into service `ProgramArguments`, and persists +`OPENCLAW_WRAPPER` in the service environment for later forced reinstalls, updates, and doctor +repairs. + +```bash +OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force +openclaw doctor +``` + +To remove a persisted wrapper, clear `OPENCLAW_WRAPPER` while reinstalling: + +```bash +OPENCLAW_WRAPPER= openclaw gateway install --force +openclaw gateway restart +``` + - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`