diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 6aa8d9ebaf9..946a814940a 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -1111,14 +1111,10 @@ In those cases NemoClaw treats an unavailable sandbox-side probe as non-blocking ### `host.docker.internal` does not reliably reach the host from the sandbox -Configuring an inference provider with a base URL like -`http://host.docker.internal:11434/v1` does not reliably reach a host Ollama -service from inside the OpenShell sandbox. -OpenShell runs sandboxes inside a k3s network, where `host.docker.internal` is -not a portable host-service route. Depending on the platform, it may fail DNS -resolution or resolve to an internal gateway/bridge address where the host's -port `11434` is not forwarded. The sandbox then sees a DNS failure or -`connection refused`: +Configuring an inference provider with a base URL like `http://host.docker.internal:11434/v1` does not reliably reach a host Ollama service from inside the OpenShell sandbox. +OpenShell runs sandboxes inside a k3s network, where `host.docker.internal` is not a portable host-service route. +Depending on the platform, it may fail DNS resolution or resolve to an internal gateway/bridge address where the host's port `11434` is not forwarded. +The sandbox then sees a DNS failure or `connection refused`: ```console $ getent hosts host.docker.internal @@ -1429,3 +1425,121 @@ $ nemoclaw rebuild ``` After the rebuild completes, return to the Skills page to confirm the skill is ready. + +## Hermes + +The Hermes agent is experimental. +The issues below are common problems operators encounter when running Hermes through `nemohermes`. +For setup, refer to Quickstart with Hermes (use the `nemoclaw-user-get-started` skill). + +### Port 8642 in a browser shows a blank page or `Cannot GET /` + +`nemohermes onboard` forwards port `8642`, but Hermes serves an OpenAI-compatible API at that port, not a chat dashboard. +A browser visit to `http://127.0.0.1:8642/` (or any non-API path) returns nothing renderable. + +Confirm the agent is healthy with the API health endpoint instead: + +```console +$ curl -sf http://127.0.0.1:8642/health +{"status":"ok","platform":"hermes-agent"} +``` + +Point an OpenAI-compatible client at `http://127.0.0.1:8642/v1` for chat completions. +For terminal use, run `nemohermes connect` and then `hermes` inside the sandbox. + +### `nemohermes` reports `Sandbox 'X' already exists as OpenClaw` + +Each sandbox name maps to exactly one agent type. +If a sandbox named `X` was created with the default OpenClaw agent, a later `nemohermes onboard` for the same name exits with: + +```text +Sandbox 'X' already exists as OpenClaw. +nemohermes is onboarding Hermes for this sandbox name. +Side-by-side agents are supported, but each sandbox name has one agent type. +``` + +Pick a distinct sandbox name (the Hermes default is `hermes`; a common pattern is `my-hermes`) so Hermes and OpenClaw sandboxes can coexist on the same host. +To convert an existing sandbox to Hermes instead, destroy and re-onboard: + +```console +$ nemoclaw destroy +$ NEMOCLAW_AGENT=hermes nemohermes onboard +``` + +### `nemohermes: command not found` immediately after install + +`nemohermes` is a thin shim installed alongside `nemoclaw` that pre-selects the Hermes agent. +The installer drops the shim in the same directory as `nemoclaw`; if `nemoclaw` is on `PATH` but `nemohermes` is not, the shim symlink was skipped. + +Verify the install: + +```console +$ command -v nemoclaw +$ command -v nemohermes +``` + +If only `nemoclaw` resolves, re-run the installer with `NEMOCLAW_AGENT=hermes` set so the shim is published: + +```console +$ export NEMOCLAW_AGENT=hermes +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +Equivalently, every `nemohermes ` invocation is `NEMOCLAW_AGENT=hermes nemoclaw `. + +### Choosing between OAuth and API key for the Hermes Provider + +The Hermes Provider supports two authentication paths during onboarding. +Pick OAuth when you have a Nous Portal account and an interactive terminal; pick API key when you have a long-lived `NOUS_API_KEY` and want a non-interactive flow. + +Set the method explicitly so the wizard skips the prompt: + +```console +$ # OAuth (default; interactive) +$ export NEMOCLAW_HERMES_AUTH_METHOD=oauth +$ nemohermes onboard + +$ # API key (non-interactive) +$ export NEMOCLAW_HERMES_AUTH_METHOD=api-key +$ export NOUS_API_KEY=nous_... +$ nemohermes onboard --non-interactive +``` + +`NEMOCLAW_HERMES_AUTH_METHOD` accepts `oauth`, `nous-portal-oauth`, `api-key`, and `nous-api-key`. +The `NEMOCLAW_HERMES_AUTH` and `NEMOCLAW_NOUS_AUTH_METHOD` variables are back-compatible aliases. + +If OAuth is selected and onboarding cannot open the host's default browser (a headless host or SSH session), the device-code prompt still prints the verification URL and user code to the terminal. +Copy them to a browser on any other machine to complete the flow. + +### API client returns `401 Unauthorized` against port 8642 + +Hermes uses bearer-token header authentication for client requests, not an OpenClaw-style URL fragment. +A request without an `Authorization: Bearer ` header (or with an OpenClaw `#token=` fragment appended to the URL) is rejected with `401`. + +Configure your OpenAI-compatible client to pass the Hermes API key in the `Authorization` header. +Stored credentials (including `NOUS_API_KEY` and `OPENAI_API_KEY`) are listed by: + +```console +$ nemohermes credentials list +``` + +Reset a specific provider's credentials with `nemohermes credentials reset ` and re-onboard if the stored value is wrong. + +### `Brave Search` policy preset has no effect under Hermes + +The Hermes wizard intentionally omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration (see Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) and Network Policies (use the `nemoclaw-user-reference` skill)). +If you add the `brave` preset to a Hermes sandbox after onboarding, the L7 egress allowlist opens for Brave's endpoints but the agent itself does not start consuming the credential. +Configure Hermes web search from the agent's own configuration inside the sandbox. + +### Re-onboarding asks every messaging prompt again + +`nemohermes onboard --resume` against a Hermes sandbox that was originally onboarded with Telegram, Discord, and Slack credentials re-prompts for each channel's bot token and per-channel settings rather than reusing the stored values. +This is tracked in [#3581](https://github.com/NVIDIA/NemoClaw/issues/3581). +For unattended re-onboards, export the messaging env vars first so the wizard skips the prompts: + +```console +$ export TELEGRAM_BOT_TOKEN=... +$ export DISCORD_BOT_TOKEN=... +$ export SLACK_BOT_TOKEN=... +$ nemohermes onboard --resume --non-interactive +``` diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index b89ebeac30a..9fda0734310 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -1124,14 +1124,10 @@ In those cases NemoClaw treats an unavailable sandbox-side probe as non-blocking ### `host.docker.internal` does not reliably reach the host from the sandbox -Configuring an inference provider with a base URL like -`http://host.docker.internal:11434/v1` does not reliably reach a host Ollama -service from inside the OpenShell sandbox. -OpenShell runs sandboxes inside a k3s network, where `host.docker.internal` is -not a portable host-service route. Depending on the platform, it may fail DNS -resolution or resolve to an internal gateway/bridge address where the host's -port `11434` is not forwarded. The sandbox then sees a DNS failure or -`connection refused`: +Configuring an inference provider with a base URL like `http://host.docker.internal:11434/v1` does not reliably reach a host Ollama service from inside the OpenShell sandbox. +OpenShell runs sandboxes inside a k3s network, where `host.docker.internal` is not a portable host-service route. +Depending on the platform, it may fail DNS resolution or resolve to an internal gateway/bridge address where the host's port `11434` is not forwarded. +The sandbox then sees a DNS failure or `connection refused`: ```console $ getent hosts host.docker.internal @@ -1442,3 +1438,120 @@ $ nemoclaw rebuild ``` After the rebuild completes, return to the Skills page to confirm the skill is ready. + +## Hermes + +The issues below are common problems you may encounter when running Hermes through `nemohermes`. +For setup, refer to [Quickstart with Hermes](/get-started/quickstart-hermes). + +### Port 8642 in a browser shows a blank page or `Cannot GET /` + +`nemohermes onboard` forwards port `8642`, but Hermes serves an OpenAI-compatible API at that port, not a chat dashboard. +A browser visit to `http://127.0.0.1:8642/` (or any non-API path) returns nothing renderable. + +Confirm the agent is healthy with the API health endpoint instead: + +```console +$ curl -sf http://127.0.0.1:8642/health +{"status":"ok","platform":"hermes-agent"} +``` + +Point an OpenAI-compatible client at `http://127.0.0.1:8642/v1` for chat completions. +For terminal use, run `nemohermes connect` and then `hermes` inside the sandbox. + +### `nemohermes` reports `Sandbox 'X' already exists as OpenClaw` + +Each sandbox name maps to exactly one agent type. +If a sandbox named `X` was created with the default OpenClaw agent, a later `nemohermes onboard` for the same name exits with: + +```text +Sandbox 'X' already exists as OpenClaw. +nemohermes is onboarding Hermes for this sandbox name. +Side-by-side agents are supported, but each sandbox name has one agent type. +``` + +Pick a distinct sandbox name (the Hermes default is `hermes`; a common pattern is `my-hermes`) so Hermes and OpenClaw sandboxes can coexist on the same host. +To convert an existing sandbox to Hermes instead, destroy and re-onboard: + +```console +$ nemoclaw destroy +$ NEMOCLAW_AGENT=hermes nemohermes onboard +``` + +### `nemohermes: command not found` immediately after install + +`nemohermes` is a thin shim installed alongside `nemoclaw` that pre-selects the Hermes agent. +The installer drops the shim in the same directory as `nemoclaw`; if `nemoclaw` is on `PATH` but `nemohermes` is not, the shim symlink was skipped. + +Verify the install: + +```console +$ command -v nemoclaw +$ command -v nemohermes +``` + +If only `nemoclaw` resolves, re-run the installer with `NEMOCLAW_AGENT=hermes` set so the shim is published: + +```console +$ export NEMOCLAW_AGENT=hermes +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +Equivalently, every `nemohermes ` invocation is `NEMOCLAW_AGENT=hermes nemoclaw `. + +### Choosing between OAuth and API key for the Hermes Provider + +The Hermes Provider supports two authentication paths during onboarding. +Pick OAuth when you have a Nous Portal account and an interactive terminal; pick API key when you have a long-lived `NOUS_API_KEY` and want a non-interactive flow. + +Set the method explicitly so the wizard skips the prompt: + +```console +$ # OAuth (default; interactive) +$ export NEMOCLAW_HERMES_AUTH_METHOD=oauth +$ nemohermes onboard + +$ # API key (non-interactive) +$ export NEMOCLAW_HERMES_AUTH_METHOD=api-key +$ export NOUS_API_KEY=nous_... +$ nemohermes onboard --non-interactive +``` + +`NEMOCLAW_HERMES_AUTH_METHOD` accepts `oauth`, `nous-portal-oauth`, `api-key`, and `nous-api-key`. +The `NEMOCLAW_HERMES_AUTH` and `NEMOCLAW_NOUS_AUTH_METHOD` variables are back-compatible aliases. + +If OAuth is selected and onboarding cannot open the host's default browser (a headless host or SSH session), the device-code prompt still prints the verification URL and user code to the terminal. +Copy them to a browser on any other machine to complete the flow. + +### API client returns `401 Unauthorized` against port 8642 + +Hermes uses bearer-token header authentication for client requests, not an OpenClaw-style URL fragment. +A request without an `Authorization: Bearer ` header (or with an OpenClaw `#token=` fragment appended to the URL) is rejected with `401`. + +Configure your OpenAI-compatible client to pass the Hermes API key in the `Authorization` header. +Stored credentials (including `NOUS_API_KEY` and `OPENAI_API_KEY`) are listed by: + +```console +$ nemohermes credentials list +``` + +Reset a specific provider's credentials with `nemohermes credentials reset ` and re-onboard if the stored value is wrong. + +### `Brave Search` policy preset has no effect under Hermes + +The Hermes wizard intentionally omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration (see [Quickstart with Hermes](/get-started/quickstart-hermes) and [Network Policies](/reference/network-policies)). +If you add the `brave` preset to a Hermes sandbox after onboarding, the L7 egress allowlist opens for Brave's endpoints but the agent itself does not start consuming the credential. +Configure Hermes web search from the agent's own configuration inside the sandbox. + +### Re-onboarding asks every messaging prompt again + +`nemohermes onboard --resume` against a Hermes sandbox that was originally onboarded with Telegram, Discord, and Slack credentials re-prompts for each channel's bot token and per-channel settings rather than reusing the stored values. +This is tracked in [#3581](https://github.com/NVIDIA/NemoClaw/issues/3581). +For unattended re-onboards, export the messaging env vars first so the wizard skips the prompts: + +```console +$ export TELEGRAM_BOT_TOKEN=... +$ export DISCORD_BOT_TOKEN=... +$ export SLACK_BOT_TOKEN=... +$ nemohermes onboard --resume --non-interactive +```