docs: add OpenClaw gateway recovery ladder

[WilliamK112]

Summary

• document the startup order and relationship between the host-side OpenShell gateway and the in-sandbox OpenClaw gateway
• add a sandbox_container_stopped recovery ladder: start the stopped Docker container, run status recovery, recover the in-sandbox gateway/forwards, rebuild only as a last resort
• replace the previous direct onboard guidance for stopped sandboxes with state-preserving recovery steps

Closes #6031

Validation

• git diff --check
• rg -n "OpenShell gateway and OpenClaw gateway startup order|sandbox_container_stopped|openshell.ai/sandbox-name|docker start <container-name>" docs/reference/troubleshooting.mdx

Note: npm run docs:check-agent-variants still fails on existing unrelated generated-doc drift: docs/reference/commands-nemohermes.mdx is out of sync.

Summary by CodeRabbit

• Documentation
  • Expanded troubleshooting guidance for gateway startup order and recovery after host reboots or gateway downtime.
  • Added clearer step-by-step procedures for sandboxes that appear stopped, including when to start, recover, rebuild, or re-onboard.
  • Included updated guidance on using status and recovery commands to restore access with minimal disruption, plus a final fallback for intentionally deleted sandboxes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bdb4da8d-8346-4435-b541-54141b9ee7b3

📥 Commits

Reviewing files that changed from the base of the PR and between d2eb9df and fd4f1b4.

📒 Files selected for processing (1)

• docs/reference/troubleshooting.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/reference/troubleshooting.mdx

---

📝 Walkthrough

Walkthrough

Documentation-only update to troubleshooting.mdx adding a section on OpenShell/OpenClaw gateway startup order and expanding the "Sandbox shows as stopped" guidance into a graded recovery procedure covering container restart, status-based recovery, in-sandbox gateway recovery, and rebuild as a last resort.

Changes

Troubleshooting Documentation

Layer / File(s)	Summary
Gateway startup order guidance docs/reference/troubleshooting.mdx	New section explains the host-side OpenShell gateway and in-sandbox OpenClaw gateway, the correct startup order, and which $$nemoclaw status/recover/gateway restart commands apply depending on reachability.
Sandbox stopped recovery ladder docs/reference/troubleshooting.mdx	Expands the "Sandbox shows as stopped" guidance into a step-by-step procedure: check/start the labeled Docker container, run status for non-destructive recovery, use recover for gateway/forwards issues, and rebuild with --yes only as a last resort, plus a note on destroy/onboard for intentional deletions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

area: sandbox, bug-fix

Possibly related PRs

• NVIDIA/NemoClaw#4580: Documents the OpenShell gateway lifecycle and fallback behavior, which is closely related to this troubleshooting update.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main documentation change about OpenClaw gateway recovery.
Linked Issues check	✅ Passed	The docs now cover gateway startup order and the restart→status→recover→rebuild recovery ladder requested in #6031.
Out of Scope Changes check	✅ Passed	The PR stays within the requested troubleshooting documentation updates and adds no unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/troubleshooting.mdx (1)

617-617: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a <Warning> callout for this caution.

This line warns against a specific misstep ("Do not start the OpenClaw gateway by hand before the OpenShell gateway is healthy...") that could cause a broken state. As per coding guidelines, docs/**/*.mdx pages should "use Fern callout components such as <Note>, <Tip>, and <Warning> for callouts in MDX pages," and this warning-style content is a good fit for a <Warning> block rather than inline prose.

📝 Proposed callout

-Do not start the OpenClaw gateway by hand before the OpenShell gateway is healthy, because NemoClaw cannot select, inspect, or reconnect the sandbox until OpenShell can see the owning gateway.
+<Warning>
+Do not start the OpenClaw gateway by hand before the OpenShell gateway is healthy.
+NemoClaw cannot select, inspect, or reconnect the sandbox until OpenShell can see the owning gateway.
+</Warning>

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/reference/troubleshooting.mdx` at line 617, The troubleshooting note in
the MDX content is written as inline prose but should be converted into a Fern
callout. Update the section containing the OpenClaw/OpenShell caution to use a
<Warning> block in the same way other MDX callouts are handled, keeping the
warning text inside that component so it renders consistently with the docs
guidelines.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/reference/troubleshooting.mdx`:
- Line 617: The troubleshooting note in the MDX content is written as inline
prose but should be converted into a Fern callout. Update the section containing
the OpenClaw/OpenShell caution to use a <Warning> block in the same way other
MDX callouts are handled, keeping the warning text inside that component so it
renders consistently with the docs guidelines.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ef5056d2-dd7f-4fe7-8258-f4651db5e52c

📥 Commits

Reviewing files that changed from the base of the PR and between e4b9111 and d2eb9df.

📒 Files selected for processing (1)

• docs/reference/troubleshooting.mdx

[wscurran]

✨ Thanks for the fix. Adding a local cleanup fallback for destroy --force when the gateway is unreachable is a solid improvement for sandbox recovery.

---

Related open issues:

• #6031 [All Platforms][Docs] troubleshooting.mdx lacks gateway startup order and a sandbox_container_stopped recovery ladder

[miyoungc]

Thanks for the contribution. Please pause and re-check the repository requirements before requesting further review.

NemoClaw has several layers of contributor guidance that must be followed for every PR: CONTRIBUTING.md, AGENTS.md, the PR template, and the relevant repo skills/workflow instructions. In particular, contributor-owned PRs must include the required DCO Signed-off-by: declaration and every commit must appear as Verified in GitHub before maintainers spend time on review.

If you are using an AI coding agent, please make sure it is actually reading and following those repo instructions. The repeated misses here should be fixed in your agent workflow before opening or updating more PRs.