#21806: CLI: add optional gateway context path for node run/install
docs
gateway
cli
commands
size: S
Cluster:
Node and macOS Enhancements
## Summary
原先 `openclaw node run` / `openclaw node install` 仅支持指定 host + port(以及可选的 TLS),连接地址形如:`ws://host:port` 或 `wss://host:port`。当 Gateway 部署在反向代理或负载均衡后面、且 WebSocket 挂在非根路径时(例如 `https://example.com/context/`),节点无法正确连上。
本次改动在保持原有 host/port 用法不变的前提下,增加可选的**上下文路径(context path)**配置,使连接 URL 变为:`wss://host:port/context/`(示例),从而支持通过带 path 的远程 Gateway 地址连接。
## Changes
- **docs/cli/node.md**: 文档补充 `--context <path>` 说明(run / install 两处)
- **src/cli/node-cli/register.ts**: `node run` 与 `node install` 增加 `--context <path>` 选项,并传入 runner/daemon
- **src/node-host/config.ts**: `NodeHostGatewayConfig` 增加可选字段 `path`
- **src/node-host/runner.ts**: 新增 `normalizeGatewayPath`,拼接 URL 时使用 `scheme://host:port${path}`
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds optional `--context <path>` parameter to `openclaw node run` and `openclaw node install` commands to support Gateway deployments behind reverse proxies with non-root WebSocket paths.
**Critical Issue Found**: The `--context` parameter is not properly passed through the daemon installation chain. While `openclaw node run --context <path>` works correctly, `openclaw node install --context <path>` accepts the parameter but fails to include it in the installed service's command arguments, causing the service to run without the context path.
**Required Changes**:
- Add `context` parameter to `NodeDaemonInstallOptions` type in `daemon.ts`
- Pass context through `buildNodeInstallPlan` in `daemon.ts`
- Add context parameter to `buildNodeInstallPlan` function signature in `node-daemon-install-helpers.ts`
- Add context to `resolveNodeProgramArguments` parameters and include `--context` flag in generated command arguments in `program-args.ts`
<h3>Confidence Score: 1/5</h3>
- This PR has a critical bug that breaks the daemon install feature
- Score of 1 reflects a critical functional bug: the `--context` parameter for `openclaw node install` is accepted but not passed to the installed service, causing the service to silently fail to connect to gateways with context paths. While `node run` works correctly, the install command creates a broken service configuration.
- Critical attention needed: `src/daemon/program-args.ts`, `src/commands/node-daemon-install-helpers.ts`, and `src/cli/node-cli/daemon.ts` must be updated to properly pass the context parameter through the installation chain
<sub>Last reviewed commit: 63ac088</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#6064: fix(daemon): prefer bundled node from install-cli.sh over system node
by joyshmitz · 2026-02-01
74.8%
#11455: fix(gateway): default gateway.mode to local when unset
by AnonO6 · 2026-02-07
71.0%
#5496: Fix: Windows path separators stripped in Gateway scheduled task
by giuliozelante · 2026-01-31
70.2%
#12834: docs(gateway): clarify there is no standalone clawrouter binary
by JBrady · 2026-02-09
70.1%
#18112: fix(daemon): gateway install on macOS ignores fnm/nvm node (#18090)
by yinghaosang · 2026-02-16
69.4%
#12804: fix(daemon): use wrapper script for pnpm global installs in service...
by odinho · 2026-02-09
69.4%
#22341: fix(status): detect node-only mode and show remote gateway info
by therk · 2026-02-21
68.9%
#6039: fix: improve type safety in gateway registration
by Bharadwajreddy1406 · 2026-02-01
68.8%
#21459: fix(gateway): resolve port from profile config, not inherited env
by kkeeling · 2026-02-19
68.8%
#9200: Fix: Strip dangerous env vars from baseEnv in host execution
by vishaltandale00 · 2026-02-05
68.5%