docs(troubleshooting): add Hermes section#4169
Merged
miyoungc merged 4 commits intoJun 2, 2026
Merged
Conversation
3 tasks
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (2)
📝 WalkthroughWalkthroughClarifies that ChangesTroubleshooting Documentation Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
.agents/skills/nemoclaw-user-reference/references/troubleshooting.md (1)
1390-1391: ⚡ Quick winReplace superlative phrasing with neutral wording.
“most common surprises” reads like marketing/superlative language; prefer direct factual wording. LLM pattern detected.
As per coding guidelines, "Superlatives and marketing language ('powerful,' 'robust,' 'seamless,' 'cutting-edge'). Say what it does, not how great it is."
🤖 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 @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md around lines 1390 - 1391, Replace the superlative/marketing phrasing in the Troubleshooting intro: change the sentence "The issues below cover the most common surprises operators hit when running Hermes through `nemohermes`." to neutral factual wording such as "The issues below cover common or frequent issues operators encounter when running Hermes through `nemohermes`." Update only that phrase in the .agents/skills/nemoclaw-user-reference/references/troubleshooting.md content so it uses "common" or "frequent issues" (or similar neutral wording) and keep the next sentence about Quickstart with Hermes unchanged.docs/reference/troubleshooting.mdx (1)
1403-1403: ⚡ Quick winUse direct second-person voice in the section intro.
“The issues below cover the most common surprises operators hit…” addresses a generic audience instead of the reader; prefer “you” phrasing to match the docs voice standard.
As per coding guidelines, "Second person ("you") when addressing the reader."
🤖 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 1403, Replace the section intro sentence "The issues below cover the most common surprises operators hit when running Hermes through `nemohermes`." with a direct second-person phrasing that addresses the reader (for example: "The issues below cover the most common surprises you may encounter when running Hermes with `nemohermes`.") so the intro uses "you" and matches the docs' voice standard.
🤖 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.
Inline comments:
In @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md:
- Around line 1078-1085: The subsection contains multiple sentences on the same
source line (e.g., the line beginning "Configuring an inference provider with a
base URL like `http://host.docker.internal:11434/v1`..."); update the paragraph
in .agents/skills/nemoclaw-user-reference/references/troubleshooting.md so every
sentence is on its own line — split the long sentence about OpenShell/k3s and
the sentence describing the sandbox DNS/connection failures into separate lines,
and ensure each remaining sentence in that subsection follows the
one-sentence-per-line rule.
---
Nitpick comments:
In @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md:
- Around line 1390-1391: Replace the superlative/marketing phrasing in the
Troubleshooting intro: change the sentence "The issues below cover the most
common surprises operators hit when running Hermes through `nemohermes`." to
neutral factual wording such as "The issues below cover common or frequent
issues operators encounter when running Hermes through `nemohermes`." Update
only that phrase in the
.agents/skills/nemoclaw-user-reference/references/troubleshooting.md content so
it uses "common" or "frequent issues" (or similar neutral wording) and keep the
next sentence about Quickstart with Hermes unchanged.
In `@docs/reference/troubleshooting.mdx`:
- Line 1403: Replace the section intro sentence "The issues below cover the most
common surprises operators hit when running Hermes through `nemohermes`." with a
direct second-person phrasing that addresses the reader (for example: "The
issues below cover the most common surprises you may encounter when running
Hermes with `nemohermes`.") so the intro uses "you" and matches the docs' voice
standard.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: efe9aa65-3ddd-49fa-9696-9dc952357b0b
📒 Files selected for processing (2)
.agents/skills/nemoclaw-user-reference/references/troubleshooting.mddocs/reference/troubleshooting.mdx
Contributor
|
✨ Thanks for submitting this detailed PR about adding a Hermes section to the troubleshooting documentation. This proposes a way to improve the documentation for common issues encountered when running Hermes through nemohermes. Related open PRs:
Related open issues: |
a84bc93 to
a46d1ad
Compare
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.agents/skills/nemoclaw-user-reference/references/troubleshooting.md (1)
1-1500:⚠️ Potential issue | 🟠 Major | ⚡ Quick winKeep documentation edits in
docs/source pages only.This PR includes direct changes to a generated mirror file under
.agents/skills/...; that risks source/mirror drift and bypasses the intended docs workflow.As per coding guidelines, "
docs/**/*.{md,mdx}: For normal documentation changes, include only source pages underdocs/; the docs-to-skills hook runs in dry-run mode to validate generated output."🤖 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 @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md around lines 1 - 1500, You edited the generated mirror of the Troubleshooting page instead of the docs source; revert your edits to the generated mirror (undo changes to the “Troubleshooting” mirror file) and apply your content changes to the canonical docs source Troubleshooting page under the docs/ source tree, then run the docs-to-skills validation hook (dry-run) to confirm the generated output matches and only docs/**/*.{md,mdx} were changed before committing.
🧹 Nitpick comments (2)
docs/reference/troubleshooting.mdx (2)
1511-1511: ⚡ Quick winUse active voice for the issue reference sentence.
“This is tracked in
#3581.” is passive; prefer an active form (for example, “Issue#3581tracks this behavior.”).As per coding guidelines, "Active voice required. Flag passive constructions."
🤖 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 1511, Change the passive sentence "This is tracked in `#3581`." to an active-voice form such as "Issue `#3581` tracks this behavior." — edit the sentence that contains the issue reference (`#3581`) so it uses an active subject ("Issue `#3581`") and an active verb ("tracks") instead of the passive construction.
1426-1428: ⚡ Quick winUse active voice in the sandbox-type conflict explanation.
The sentence “If a sandbox named
Xwas created…” is passive; rewrite it in active voice.As per coding guidelines, "Active voice required. Flag passive constructions."
🤖 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` around lines 1426 - 1428, The sentence "If a sandbox named `X` was created with the default OpenClaw agent, a later `nemohermes onboard` for the same name exits with:" uses passive voice; rewrite it in active voice so the subject performs the action — e.g., "When you create a sandbox named `X` with the default OpenClaw agent, running `nemohermes onboard` later for the same name exits with:" — update the sentence in docs/reference/troubleshooting.mdx replacing the passive construction (the sentence beginning "If a sandbox named `X` was created...") with an active-voice variant.
🤖 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.
Outside diff comments:
In @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md:
- Around line 1-1500: You edited the generated mirror of the Troubleshooting
page instead of the docs source; revert your edits to the generated mirror (undo
changes to the “Troubleshooting” mirror file) and apply your content changes to
the canonical docs source Troubleshooting page under the docs/ source tree, then
run the docs-to-skills validation hook (dry-run) to confirm the generated output
matches and only docs/**/*.{md,mdx} were changed before committing.
---
Nitpick comments:
In `@docs/reference/troubleshooting.mdx`:
- Line 1511: Change the passive sentence "This is tracked in `#3581`." to an
active-voice form such as "Issue `#3581` tracks this behavior." — edit the
sentence that contains the issue reference (`#3581`) so it uses an active subject
("Issue `#3581`") and an active verb ("tracks") instead of the passive
construction.
- Around line 1426-1428: The sentence "If a sandbox named `X` was created with
the default OpenClaw agent, a later `nemohermes onboard` for the same name exits
with:" uses passive voice; rewrite it in active voice so the subject performs
the action — e.g., "When you create a sandbox named `X` with the default
OpenClaw agent, running `nemohermes onboard` later for the same name exits
with:" — update the sentence in docs/reference/troubleshooting.mdx replacing the
passive construction (the sentence beginning "If a sandbox named `X` was
created...") with an active-voice variant.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 52f44745-be78-481f-8b7e-69da3a18dc16
📒 Files selected for processing (2)
.agents/skills/nemoclaw-user-reference/references/troubleshooting.mddocs/reference/troubleshooting.mdx
Append a new `## Hermes` section to `docs/reference/troubleshooting.mdx`
covering the most common surprises operators hit when running Hermes
through `nemohermes`:
- Port 8642 returns blank page or `Cannot GET /` (Hermes serves an
OpenAI-compat API at that port, not a chat dashboard).
- `Sandbox 'X' already exists as OpenClaw` (each sandbox name maps
to one agent type).
- `nemohermes: command not found` immediately after install (shim
publication path).
- Choosing between OAuth and API key (`NEMOCLAW_HERMES_AUTH_METHOD`
and the back-compat aliases).
- `401 Unauthorized` against port 8642 (Hermes requires
`Authorization: Bearer`, not the OpenClaw `#token=` fragment).
- `Brave Search` policy preset has no effect under Hermes (Hermes
does not use NemoClaw's OpenClaw web-search configuration).
- Re-onboarding asks every messaging prompt again (tracked in
NVIDIA#3581; documents the env-var workaround).
Cross-references use absolute paths (`/get-started/quickstart-hermes`,
`/reference/network-policies`) per the file's convention post Fern
MDX migration (NVIDIA#3837) and per the CodeRabbit nit on the original PR.
The mirror at
`.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`
is regenerated by `scripts/docs-to-skills.py`.
Fresh recreation of the closed NVIDIA#3658 rebuilt cleanly on top of
current upstream/main as a single signed commit.
Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com>
…ternal note
Three CodeRabbit nits on the Hermes troubleshooting section:
- The host.docker.internal paragraph was hard-wrapped at ~80 chars, so a
few sentences landed on the same source line. Reflow to
one-sentence-per-line for cleaner diffs.
- The Hermes intro used "the most common surprises operators hit".
Drop the superlative phrasing for neutral wording.
- In the .mdx (user-facing) file, address the reader in second person
("you may encounter") instead of generic "operators hit". The .md
agent-mirror keeps the impersonal form used elsewhere in that file.
Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com>
a46d1ad to
e6ee234
Compare
miyoungc
reviewed
Jun 2, 2026
miyoungc
approved these changes
Jun 2, 2026
This was referenced Jun 2, 2026
This was referenced Jun 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Append a
## Hermessection todocs/reference/troubleshooting.mdxcovering the most common surprises operators hit when running Hermes throughnemohermes.Related Issue
Fresh recreation of the closed #3658.
Changes
## Hermestroubleshooting section todocs/reference/troubleshooting.mdxwith the following entries:Cannot GET /: Hermes serves an OpenAI-compatible API at that port, not a chat dashboard; documents the/healthcheck and the/v1client URL.Sandbox 'X' already exists as OpenClaw: explains the one-agent-per-sandbox-name rule and the destroy plus re-onboard pattern to convert.nemohermes: command not foundimmediately after install: covers the shim publication path and theNEMOCLAW_AGENT=hermesre-install workaround.NEMOCLAW_HERMES_AUTH_METHODaccepted values, theNEMOCLAW_HERMES_AUTHandNEMOCLAW_NOUS_AUTH_METHODback-compat aliases, and the headless-host device-code fallback.401 Unauthorizedagainst port 8642: Hermes requires anAuthorization: Bearerheader, not the OpenClaw#token=URL fragment.Brave Searchpolicy preset has no effect under Hermes: Hermes does not use NemoClaw's OpenClaw web-search configuration; explains the wizard omission and why adding the preset post-onboard opens egress without wiring it into the agent./get-started/quickstart-hermes,/reference/network-policies) per the file's convention after the Fern MDX migration (docs: remove legacy markdown docs and refresh MDX checks #3837). The original PR landed with relative.mdpaths flagged in review; this recreation uses absolute paths from the first commit.Type of Change
Verification
npx prek run --all-filespassesnpm testpassesnpm run docsbuilds without warnings (doc changes only)Ran:
python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-run(clean);markdownlint-cli2(clean). Pre-commit hooks pass except the pre-existingtsc-plugininfra failure present on stockupstream/main.Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com
Summary by CodeRabbit