docs(troubleshooting): add Hermes section by latenighthackathon · Pull Request #3658 · NVIDIA/NemoClaw

latenighthackathon · 2026-05-17T02:09:08Z

Summary

docs/reference/troubleshooting.mdx had no Hermes coverage even though Hermes is a supported experimental agent path with several patterns that trip up new operators. Adds a ## Hermes section covering the most common surprises hit through nemohermes.

Entries added

Each subsection pairs the user-visible symptom with a verified remediation:

Subsection	Symptom
Port 8642 in a browser shows a blank page or `Cannot GET /`	Operator opened forwarded port in browser expecting a chat dashboard
`nemohermes` reports `Sandbox 'X' already exists as OpenClaw`	Agent-type collision under a sandbox name
`nemohermes: command not found` immediately after install	Installer skipped the shim symlink
Choosing between OAuth and API key for the Hermes Provider	`NEMOCLAW_HERMES_AUTH_METHOD` accepted values + headless-OAuth fallback
API client returns `401 Unauthorized` against port 8642	URL fragment vs bearer header confusion
`Brave Search` policy preset has no effect under Hermes	Preset is a no-op for the Hermes agent
Re-onboarding asks every messaging prompt again	Tracked in #3581; documents the env-var workaround

Migration alignment

Cross-references use absolute paths (/get-started/quickstart-hermes, /reference/network-policies) to match the post-#3837 MDX convention. The existing in-file pattern already used absolute paths; the new section now matches.

Related Issue

No specific closing issue. Tracks the doc gap surfaced by Hermes shipping as experimental without troubleshooting coverage; references #3581 for the messaging re-prompt entry.

Files

docs/reference/troubleshooting.mdx (new ## Hermes section)
.agents/skills/nemoclaw-user-reference/references/troubleshooting.md (auto-generated mirror)

Test plan

prek run clean
Rendered locally; tables, code fences, and cross-refs all resolve
Verified each cited cause path against current code: port 8642 binding, nemohermes shim install, NEMOCLAW_HERMES_AUTH_METHOD env var, gateway-credential plumbing for /v1 requests, brave preset behavior under Hermes

Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com

copy-pr-bot · 2026-05-17T02:09:11Z

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 · 2026-05-17T02:09:19Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds Hermes-specific troubleshooting to operator reference docs, covering port 8642 API behavior, sandbox naming conflicts, missing shim/install verification, provider auth selection, 401 remediation, Brave Search policy notes, and re-onboarding messaging workflows.

Changes

Hermes Troubleshooting Operator Guide

Layer / File(s)	Summary
Hermes troubleshooting section introduction `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Introduced Hermes troubleshooting section with experimental scope notice and link to Hermes quickstart documentation.
Port 8642 OpenAI-compatible API expectations and verification `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Documented that port 8642 serves an OpenAI-compatible API endpoint (not a chat dashboard), provided `/health` health check curl examples, and clarified correct client configuration and terminal connection usage.
Sandbox name collision resolution between OpenClaw and Hermes `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Explained one-agent-type-per-sandbox-name constraint and provided destroy + re-onboard commands using `NEMOCLAW_AGENT=hermes` to convert existing sandboxes.
Nemohermes installation verification and shim publishing `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Troubleshooting for `nemohermes: command not found` covering shim/symlink publishing behavior, PATH verification steps, and reinstall instructions with `NEMOCLAW_AGENT=hermes` to republish the shim.
Hermes provider authentication method selection and configuration `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Documented `NEMOCLAW_HERMES_AUTH_METHOD` configuration choices (OAuth vs API key), enumerated accepted values and legacy aliases, and provided device-code verification behavior guidance for headless and SSH environments.
401 Unauthorized errors and credential management `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Added remediation for `401 Unauthorized` against port 8642 requiring `Authorization: Bearer <token>` header format and documented credential list/reset commands for re-authentication.
Policy preset behavior and re-onboarding messaging workflows `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md`, `docs/reference/troubleshooting.mdx`	Clarified that Brave Search policy preset has no effect under Hermes and documented `--resume` re-prompting of messaging credentials with environment-variable export + `--non-interactive` workaround for unattended re-onboarding.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

ericksoa

Poem

🐰 I hopped through docs to help you see,
Ports, shims, and auth—clear as can be,
Sandbox names aligned, tokens in hand,
Re-onboard smooth across the land,
Hooray for Hermes—now debug with glee! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title directly summarizes the main change: adding a Hermes troubleshooting section to documentation.
Linked Issues check	✅ Passed	The PR adds Hermes troubleshooting documentation including environment variables (NEMOCLAW_HERMES_AUTH_METHOD, NEMOCLAW_AGENT), addressing the environment-variable consolidation goal from issue `#3059` [`#3059`].
Out of Scope Changes check	✅ Passed	All changes are focused on adding Hermes troubleshooting documentation to two files as intended; no unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

coderabbitai

🧹 Nitpick comments (2)

docs/reference/troubleshooting.md (2)
1331-1331: ⚡ Quick win

Remove the colon from this heading.

Line 1331 uses a colon in a section title, which violates the title-format rule.

As per coding guidelines, "No colons in titles. Flag 'Inference: Cloud and Local' — should be 'Cloud and Local Inference.'"
🤖 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.md` at line 1331, The section heading "Hermes
Provider authentication: choosing between OAuth and API key" contains a colon
which violates the title-format rule; edit that heading (the exact string
"Hermes Provider authentication: choosing between OAuth and API key") to remove
the colon — e.g. change it to "Hermes Provider authentication choosing between
OAuth and API key" or use a dash/parentheses if you prefer ("Hermes Provider
authentication — choosing between OAuth and API key") so the colon character is
eliminated.
1278-1278: ⚡ Quick win

Drop unnecessary bold emphasis on routine instructions (LLM pattern detected).

Lines 1278 and 1357 bold routine descriptive phrases that are not UI labels, parameter names, or warnings.

As per coding guidelines, "Unnecessary bold on routine instructions ... should be flagged." LLM pattern detected.

Also applies to: 1357-1357
🤖 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.md` at line 1278, The doc uses strong/bold
markup for routine descriptive phrases (LLM pattern) in the sentence about
`nemohermes onboard` forwarding port `8642` and a second occurrence later;
locate the bolded phrases (e.g., "**OpenAI-compatible API**" and the other
bolded routine phrase near the same section) in
docs/reference/troubleshooting.md and remove the bold markup so the phrases are
plain text while leaving UI labels, parameter names (like `nemohermes onboard`
and `8642`) unchanged.

🤖 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.md`:
- Line 1331: The section heading "Hermes Provider authentication: choosing
between OAuth and API key" contains a colon which violates the title-format
rule; edit that heading (the exact string "Hermes Provider authentication:
choosing between OAuth and API key") to remove the colon — e.g. change it to
"Hermes Provider authentication choosing between OAuth and API key" or use a
dash/parentheses if you prefer ("Hermes Provider authentication — choosing
between OAuth and API key") so the colon character is eliminated.
- Line 1278: The doc uses strong/bold markup for routine descriptive phrases
(LLM pattern) in the sentence about `nemohermes onboard` forwarding port `8642`
and a second occurrence later; locate the bolded phrases (e.g.,
"**OpenAI-compatible API**" and the other bolded routine phrase near the same
section) in docs/reference/troubleshooting.md and remove the bold markup so the
phrases are plain text while leaving UI labels, parameter names (like
`nemohermes onboard` and `8642`) unchanged.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 59cfc5b2-400e-438c-bb36-c73f1e9ee968

📥 Commits

Reviewing files that changed from the base of the PR and between aa6dca9 and 5e56968.

📒 Files selected for processing (2)

.agents/skills/nemoclaw-user-reference/references/troubleshooting.md
docs/reference/troubleshooting.md

wscurran · 2026-05-18T14:56:12Z

✨ Thanks for submitting this detailed PR to add a Hermes section to the troubleshooting documentation. This change aims to improve the documentation coverage for Hermes, which is a supported experimental agent path with several patterns that can trip up new operators.

Related open issues:

#3059 Missing proper reference of ALL environment variables
#3581 [Ubuntu 22.04][Onboard] nemohermes re-onboard re-asks all 5 messaging per-channel prompts; credentials.json never written; "Messaging: none" on Run 2 review

miyoungc · 2026-05-19T23:44:28Z

Docs migration heads-up: #3837 has merged the Fern MDX migration cleanup.

Legacy documentation source pages under docs/**/*.md have been removed, except for docs/CONTRIBUTING.md. Please update this PR so any documentation changes target the matching Fern MDX page under docs/**/*.mdx instead, for example docs/reference/commands.mdx or docs/inference/inference-options.mdx.

CI now validates the MDX sources directly, so deleted legacy Markdown pages should stay deleted.

coderabbitai

Actionable comments posted: 1

🤖 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 `@docs/reference/troubleshooting.mdx`:
- Line 1273: Update the two relative `.md` cross-references to use absolute
Fern-style paths: replace `[Quickstart with
Hermes](../get-started/quickstart-hermes.md)` with `[Quickstart with
Hermes](/get-started/quickstart-hermes)` (both occurrences) and replace
`[Network Policies](network-policies.md)` with `[Network
Policies](/reference/network-policies)` so links follow the absolute-path
convention used across the file.

🪄 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: cf20cfa4-9215-4e43-a604-1e85e63a4001

📥 Commits

Reviewing files that changed from the base of the PR and between 404ca48 and 65ab791.

📒 Files selected for processing (2)

.agents/skills/nemoclaw-user-reference/references/troubleshooting.md
docs/reference/troubleshooting.mdx

`docs/reference/troubleshooting.md` had no Hermes coverage even though Hermes is a supported experimental agent path with several patterns that trip up new operators. Add a `## Hermes` section covering the most common surprises hit through `nemohermes`: - Port 8642 returns blank/`Cannot GET /` in a browser (it's an OpenAI-compatible API at `/v1`, not a chat dashboard) - `Sandbox 'X' already exists as OpenClaw` when re-onboarding with the Hermes agent under a name already bound to OpenClaw - `nemohermes: command not found` when the installer skipped the shim - Choosing between OAuth and API-key auth via `NEMOCLAW_HERMES_AUTH_METHOD` (with all four accepted values listed) and the headless-OAuth fallback (copy verification URL from terminal) - `401 Unauthorized` against port 8642 when the client sends an OpenClaw-style `#token=` URL fragment instead of a bearer header - `Brave Search` policy preset is a no-op for Hermes (already implied in `quickstart-hermes.md` / `network-policies.md`; called out here for operators who add the preset post-onboard) - `nemohermes onboard --resume` re-asks every messaging prompt (tracked in NVIDIA#3581); the workaround is to export the token env vars All claims verified against current `src/lib/agent/`, `src/lib/hermes-provider-auth.ts`, `src/lib/onboard.ts`, and `agents/hermes/manifest.yaml`. No new env vars or flags invented; each referenced var (`NEMOCLAW_AGENT`, `NEMOCLAW_HERMES_AUTH_METHOD`, `NOUS_API_KEY`, messaging token vars) already exists and is honored by the wizard. The `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md` mirror is updated in lockstep via `python3 scripts/docs-to-skills.py`. Verification: - `markdownlint-cli2` passes - `Verify docs-to-skills output` passes - `gitleaks (secret scan)` passes - `Test (skills YAML)` passes Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com>

latenighthackathon · 2026-05-25T04:31:46Z

Closing in favor of #4169 which is rebuilt cleanly on current upstream/main with the same content + the CodeRabbit absolute-path nit applied on first commit. Cheers!

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>

## Summary Append a `## Hermes` section to `docs/reference/troubleshooting.mdx` covering the most common surprises operators hit when running Hermes through `nemohermes`. ## Related Issue Fresh recreation of the closed #3658. ## Changes - Add a `## Hermes` troubleshooting section to `docs/reference/troubleshooting.mdx` with the following entries: - Port 8642 returns a blank page or `Cannot GET /`: Hermes serves an OpenAI-compatible API at that port, not a chat dashboard; documents the `/health` check and the `/v1` client 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 found` immediately after install: covers the shim publication path and the `NEMOCLAW_AGENT=hermes` re-install workaround. - Choosing between OAuth and API key for the Hermes Provider: documents `NEMOCLAW_HERMES_AUTH_METHOD` accepted values, the `NEMOCLAW_HERMES_AUTH` and `NEMOCLAW_NOUS_AUTH_METHOD` back-compat aliases, and the headless-host device-code fallback. - `401 Unauthorized` against port 8642: Hermes requires an `Authorization: Bearer` header, not the OpenClaw `#token=` URL fragment. - `Brave Search` policy 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. - Re-onboarding asks every messaging prompt again: links #3581 and documents the env-var workaround for unattended re-onboards. - Use absolute cross-reference paths (`/get-started/quickstart-hermes`, `/reference/network-policies`) per the file's convention after the Fern MDX migration (#3837). The original PR landed with relative `.md` paths flagged in review; this recreation uses absolute paths from the first commit. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [x] Doc only (includes code sample changes) ## Verification  - [ ] `npx prek run --all-files` passes - [ ] `npm test` passes - [ ] Tests added or updated for new or changed behavior - [x] No secrets, API keys, or credentials committed - [ ] Docs updated for user-facing behavior changes - [ ] `npm run docs` builds without warnings (doc changes only) - [ ] Doc pages follow the style guide (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages 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-existing `tsc-plugin` infra failure present on stock `upstream/main`. --- Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com>  ## Summary by CodeRabbit * **Documentation** * Expanded troubleshooting with Hermes operational guidance: port 8642 expectations, sandbox name conflicts and re-onboarding, shim verification and reinstall steps, provider auth-method selection (OAuth vs API key) and non-interactive env-var setup, common 401/Auth header fixes, Brave Search preset behavior, and messaging re-onboarding with exported bot-token env vars * Clarified that host-to-sandbox routing is unreliable and recommend using the local host proxy route with diagnostic examples and tips  --------- Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com> Co-authored-by: latenighthackathon <latenighthackathon@users.noreply.github.com> Co-authored-by: Miyoung Choi <miyoungc@nvidia.com>

coderabbitai Bot reviewed May 17, 2026

View reviewed changes

latenighthackathon force-pushed the docs/hermes-troubleshooting branch from 5e56968 to 54786d3 Compare May 17, 2026 02:20

cv assigned miyoungc May 17, 2026

latenighthackathon force-pushed the docs/hermes-troubleshooting branch from e0cf333 to 404ca48 Compare May 18, 2026 02:58

wscurran added documentation enhancement New capability or improvement request integration: hermes Hermes integration behavior labels May 18, 2026

latenighthackathon force-pushed the docs/hermes-troubleshooting branch from 404ca48 to 65ab791 Compare May 20, 2026 02:05

coderabbitai Bot reviewed May 20, 2026

View reviewed changes

Comment thread docs/reference/troubleshooting.mdx Outdated

This was referenced May 20, 2026

docs: clarify Discord preset validation #3934

Merged

fix(onboard): reject host.docker.internal inference URLs #3804

Merged

latenighthackathon force-pushed the docs/hermes-troubleshooting branch 2 times, most recently from bb434ce to a0ebed8 Compare May 21, 2026 05:34

latenighthackathon force-pushed the docs/hermes-troubleshooting branch from a0ebed8 to 9a0ddbb Compare May 21, 2026 05:44

This was referenced May 21, 2026

docs: refresh release notes for v0.0.47 and v0.0.48 #4007

Merged

fix(install): add Docker group access security note in install flow and docs #4011

Merged

docs: refresh release notes for v0.0.49 #4078

Merged

latenighthackathon mentioned this pull request May 25, 2026

docs(troubleshooting): add Hermes section #4169

Merged

12 tasks

latenighthackathon closed this May 25, 2026

latenighthackathon deleted the docs/hermes-troubleshooting branch June 2, 2026 02:10

wscurran added the feature PR adds or expands user-visible functionality label Jun 3, 2026

wscurran added area: docs Documentation, examples, guides, or docs build and removed documentation enhancement New capability or improvement request labels Jun 3, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(troubleshooting): add Hermes section#3658

docs(troubleshooting): add Hermes section#3658
latenighthackathon wants to merge 1 commit into
NVIDIA:mainfrom
latenighthackathon:docs/hermes-troubleshooting

latenighthackathon commented May 17, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented May 17, 2026

Uh oh!

coderabbitai Bot commented May 17, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

wscurran commented May 18, 2026

Uh oh!

miyoungc commented May 19, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

latenighthackathon commented May 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

latenighthackathon commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Entries added

Migration alignment

Related Issue

Files

Test plan

Uh oh!

copy-pr-bot Bot commented May 17, 2026

Uh oh!

coderabbitai Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

wscurran commented May 18, 2026

Uh oh!

miyoungc commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

latenighthackathon commented May 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

latenighthackathon commented May 17, 2026 •

edited

Loading

coderabbitai Bot commented May 17, 2026 •

edited

Loading

miyoungc commented May 19, 2026 •

edited

Loading