Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix docs: clarify daemon vs foreground gateway quick start and Node service runtime checks [1 pull requests, 2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#72265•Fetched 2026-04-27 05:32:18
View on GitHub
Comments
2
Participants
3
Timeline
5
Reactions
0
Author
Iman-SharifIman-Sharif
Participants
clawsweeper[bot]clawsweeper[bot]Iman-SharifIman-SharifQEEK-AIQEEK-AI
Timeline (top)
commented ×2cross-referenced ×1mentioned ×1subscribed ×1

Fix Action

Fixed

PR fix notes

PR #72490: docs(gateway): clarify daemon quick start (Fixes #72265)

Description (problem / solution / changelog)

Summary

Problem

The README quick start showed daemon installation followed by a foreground gateway command, which can make new users run both modes at once. The Node install docs also did not show how to compare the shell Node runtime with the gateway service runtime.

Why it matters

Daemon/foreground confusion can lead to duplicate gateway or port-state troubleshooting. Node version managers can also make the shell use one Node binary while the service uses another.

What changed

  • Split the README quick start into daemon mode and foreground/debug mode.
  • Updated the README logging link to the canonical gateway logging docs path.
  • Added service runtime verification commands to the Node install docs.
  • Added the same Node/service runtime checklist to gateway troubleshooting.

What did NOT change

No runtime behavior changed.

Change Type

Documentation

Scope

Docs only:

  • README.md
  • docs/install/node.md
  • docs/gateway/troubleshooting.md

Linked Issue/PR

Closes #72265

User-visible / Behavior Changes

New users now see two separate gateway startup paths: daemon mode and foreground/debug mode.

Security Impact

No security-sensitive behavior changed.

Repro + Verification

Environment

  • macOS local checkout
  • Node v22.12.0
  • pnpm 10.33.0

Steps

  1. Review the README quick start.
  2. Review Node install and gateway troubleshooting docs for service runtime checks.
  3. Run docs lint.

Expected

The docs clearly separate daemon and foreground gateway usage, include Node/service runtime checks, and pass Markdown lint.

Actual

The requested docs are present and Markdown lint passes.

Evidence

  • pnpm lint:docs passed.
  • git diff --check passed.

pnpm format:docs:check could not run locally because oxfmt is not installed in this environment.

Human Verification

The diff was reviewed manually against the issue checklist.

Compatibility / Migration

No migration needed.

Failure Recovery

Docs-only change. Revert the commit if maintainers prefer a different quick-start layout.

Risks and Mitigations

Risk: users may miss the send-message example because it now follows the foreground/debug block. Mitigation: the quick-start section keeps the send-message and agent examples immediately below the startup paths.

Changed files

  • README.md (modified, +13/-1)
  • docs/gateway/troubleshooting.md (modified, +31/-0)
  • docs/install/node.md (modified, +33/-0)

Code Example

openclaw onboard --install-daemon
openclaw gateway --port 18789 --verbose

---

### Recommended: daemon mode
openclaw onboard --install-daemon
openclaw gateway status

### Foreground/debug mode
openclaw gateway stop
openclaw gateway --port 18789 --verbose

---

node -v
npm -v
which node
which openclaw
openclaw gateway status
systemctl --user cat openclaw-gateway.service # Linux/systemd
RAW_BUFFERClick to expand / collapse

Problem

The GitHub README quick start currently shows daemon install followed by a foreground gateway command:

openclaw onboard --install-daemon
openclaw gateway --port 18789 --verbose

For new users this can be confusing: after installing the daemon, should they also run a foreground gateway? In troubleshooting scenarios it can also obscure duplicate gateway/port/service-state issues.

Separately, the Node docs correctly state Node 24 recommended / Node 22.14+ supported, but do not clearly show how to verify the Node binary used by the gateway daemon/service versus the interactive shell.

Suggested docs fix

Split README quick start into two explicit paths:

### Recommended: daemon mode
openclaw onboard --install-daemon
openclaw gateway status

### Foreground/debug mode
openclaw gateway stop
openclaw gateway --port 18789 --verbose

Add Node service runtime checks to the Node/troubleshooting docs:

node -v
npm -v
which node
which openclaw
openclaw gateway status
systemctl --user cat openclaw-gateway.service # Linux/systemd

Explain that shell Node and service Node can differ when using nvm/fnm/mise/n or after upgrades, and that the gateway should be restarted after Node changes.

Also consider

Use canonical docs links in the README where possible, e.g. /gateway/logging instead of ambiguous /logging if the latter is only a redirect.

extent analysis

TL;DR

Update the GitHub README to separate daemon and foreground modes, and add Node version checks to the troubleshooting documentation.

Guidance

  • Split the README quick start into two explicit paths for daemon mode and foreground/debug mode to avoid confusion for new users.
  • Add commands to verify the Node binary used by the gateway daemon/service, such as node -v, npm -v, which node, and which openclaw.
  • Include a note about the potential difference between the shell Node and service Node when using version managers like nvm or after upgrades.
  • Consider using canonical docs links in the README to avoid ambiguity.

Example

### Recommended: daemon mode
openclaw onboard --install-daemon
openclaw gateway status

### Foreground/debug mode
openclaw gateway stop
openclaw gateway --port 18789 --verbose

Notes

The suggested changes aim to improve clarity and troubleshooting for users, but may not address all potential issues. Additional testing and verification may be necessary to ensure the changes are effective.

Recommendation

Apply the suggested documentation fixes to improve user experience and troubleshooting. This will help reduce confusion and provide clearer guidance for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#LLM response#prompt template#agent execution#callback error#memory management

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix docs: clarify daemon vs foreground gateway quick start and Node service runtime checks [1 pull requests, 2 comments, 3 participants]