better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/migrate-from-openclaw.md

@@ -0,0 +1,252 @@
+---
+sidebar_position: 10
+title: "Migrate from OpenClaw"
+description: "Complete guide to migrating your OpenClaw / Clawdbot setup to Hermes Agent — what gets migrated, how config maps, and what to check after."
+---
+
+# Migrate from OpenClaw
+
+`hermes claw migrate` imports your OpenClaw (or legacy Clawdbot/Moldbot) setup into Hermes. This guide covers exactly what gets migrated, the config key mappings, and what to verify after migration.
+
+:::note
+Coming from **Claude Code** or **OpenAI Codex CLI** instead? Use [`hermes import-agent`](../user-guide/import-from-other-agents.md).
+:::
+
+:::tip
+If your OpenClaw setup was multi-provider, `hermes setup --portal` collapses it to one OAuth — 300+ models plus the Tool Gateway in a single login. See [Nous Portal](/integrations/nous-portal).
+:::
+
+## Quick start
+
+```bash
+# Preview then migrate (always shows a preview first, then asks to confirm)
+hermes claw migrate
+
+# Preview only, no changes
+hermes claw migrate --dry-run
+
+# Full migration including API keys, skip confirmation
+hermes claw migrate --preset full --migrate-secrets --yes
+```
+
+The migration always shows a full preview of what will be imported before making any changes. Review the list, then confirm to proceed.
+
+Reads from `~/.openclaw/` by default. Legacy `~/.clawdbot/` or `~/.moltbot/` directories are detected automatically. Same for legacy config filenames (`clawdbot.json`, `moltbot.json`).
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview only — stop after showing what would be migrated. |
+| `--preset <name>` | `full` (all compatible settings) or `user-data` (excludes infrastructure config). Neither preset imports secrets by default — pass `--migrate-secrets` explicitly. |
+| `--overwrite` | Overwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts). |
+| `--migrate-secrets` | Include API keys. Required even under `--preset full` — no preset imports secrets silently. |
+| `--no-backup` | Skip the pre-migration zip snapshot of `~/.hermes/` (by default a single restore-point archive is written before apply, under `~/.hermes/backups/pre-migration-*.zip`; restorable with `hermes import`). |
+| `--source <path>` | Custom OpenClaw directory. |
+| `--workspace-target <path>` | Where to place `AGENTS.md`. |
+| `--skill-conflict <mode>` | `skip` (default), `overwrite`, or `rename`. |
+| `--yes` | Skip the confirmation prompt after preview. |
+
+## What gets migrated
+
+### Persona, memory, and instructions
+
+| What | OpenClaw source | Hermes destination | Notes |
+|------|----------------|-------------------|-------|
+| Persona | `workspace/SOUL.md` | `~/.hermes/SOUL.md` | Direct copy |
+| Workspace instructions | `workspace/AGENTS.md` | `AGENTS.md` in `--workspace-target` | Requires `--workspace-target` flag |
+| Long-term memory | `workspace/MEMORY.md` | `~/.hermes/memories/MEMORY.md` | Parsed into entries, merged with existing, deduped. Uses `§` delimiter. |
+| User profile | `workspace/USER.md` | `~/.hermes/memories/USER.md` | Same entry-merge logic as memory. |
+| Daily memory files | `workspace/memory/*.md` | `~/.hermes/memories/MEMORY.md` | All daily files merged into main memory. |
+
+Workspace files are also checked at `workspace.default/` and `workspace-main/` as fallback paths (OpenClaw renamed `workspace/` to `workspace-main/` in recent versions, and uses `workspace-{agentId}` for multi-agent setups).
+
+### Skills (4 sources)
+
+| Source | OpenClaw location | Hermes destination |
+|--------|------------------|-------------------|
+| Workspace skills | `workspace/skills/` | `~/.hermes/skills/openclaw-imports/` |
+| Managed/shared skills | `~/.openclaw/skills/` | `~/.hermes/skills/openclaw-imports/` |
+| Personal cross-project | `~/.agents/skills/` | `~/.hermes/skills/openclaw-imports/` |
+| Project-level shared | `workspace/.agents/skills/` | `~/.hermes/skills/openclaw-imports/` |
+
+Skill conflicts are handled by `--skill-conflict`: `skip` leaves the existing Hermes skill, `overwrite` replaces it, `rename` creates a `-imported` copy.
+
+### Model and provider configuration
+
+| What | OpenClaw config path | Hermes destination | Notes |
+|------|---------------------|-------------------|-------|
+| Default model | `agents.defaults.model` | `config.yaml` → `model` | Can be a string or `{primary, fallbacks}` object |
+| Custom providers | `models.providers.*` | `config.yaml` → `custom_providers` (auto-migrated to the canonical `providers:` dict on the next `hermes update` config migration) | Maps `baseUrl`, `apiType`/`api` — handles both short ("openai", "anthropic") and hyphenated ("openai-completions", "anthropic-messages", "google-generative-ai") values |
+| Provider API keys | `models.providers.*.apiKey` | `~/.hermes/.env` | Requires `--migrate-secrets`. See [API key resolution](#api-key-resolution) below. |
+
+### Agent behavior
+
+| What | OpenClaw config path | Hermes config path | Mapping |
+|------|---------------------|-------------------|---------|
+| Max turns | `agents.defaults.timeoutSeconds` | `agent.max_turns` | `timeoutSeconds / 10`, capped at 200 |
+| Verbose mode | `agents.defaults.verboseDefault` | `agent.verbose` | "off" / "on" / "full" |
+| Reasoning effort | `agents.defaults.thinkingDefault` | `agent.reasoning_effort` | "always"/"high"/"xhigh" → "high", "auto"/"medium"/"adaptive" → "medium", "off"/"low"/"none"/"minimal" → "low" |
+| Compression | `agents.defaults.compaction.mode` | `compression.enabled` | "off" → false, anything else → true |
+| Compression model | `agents.defaults.compaction.model` | `compression.summary_model` | Direct string copy |
+| Human delay | `agents.defaults.humanDelay.mode` | `human_delay.mode` | "natural" / "custom" / "off" |
+| Human delay timing | `agents.defaults.humanDelay.minMs` / `.maxMs` | `human_delay.min_ms` / `.max_ms` | Direct copy |
+| Timezone | `agents.defaults.userTimezone` | `timezone` | Direct string copy |
+| Exec timeout | `tools.exec.timeoutSec` | `terminal.timeout` | Direct copy (field is `timeoutSec`, not `timeout`) |
+| Docker sandbox | `agents.defaults.sandbox.backend` | `terminal.backend` | "docker" → "docker" |
+| Docker image | `agents.defaults.sandbox.docker.image` | `terminal.docker_image` | Direct copy |
+
+### Session lifetime
+
+Idle and daily reset timers are not imported: Hermes conversations persist until an explicit `/new` or `/reset`. Advanced session settings (identity links, thread bindings, maintenance, scope and send policy) remain archived for reference.
+
+### MCP servers
+
+| OpenClaw field | Hermes field | Notes |
+|----------------|-------------|-------|
+| `mcp.servers.*.command` | `mcp_servers.*.command` | Stdio transport |
+| `mcp.servers.*.args` | `mcp_servers.*.args` | |
+| `mcp.servers.*.env` | `mcp_servers.*.env` | |
+| `mcp.servers.*.cwd` | `mcp_servers.*.cwd` | |
+| `mcp.servers.*.url` | `mcp_servers.*.url` | HTTP/SSE transport |
+| `mcp.servers.*.tools.include` | `mcp_servers.*.tools.include` | Tool filtering |
+| `mcp.servers.*.tools.exclude` | `mcp_servers.*.tools.exclude` | |
+
+### TTS (text-to-speech)
+
+TTS settings are read from **two** OpenClaw config locations with this priority:
+
+1. `messages.tts.providers.{provider}.*` (canonical location)
+2. Top-level `talk.providers.{provider}.*` (fallback)
+3. Legacy flat keys `messages.tts.{provider}.*` (oldest format)
+
+| What | Hermes destination |
+|------|-------------------|
+| Provider name | `config.yaml` → `tts.provider` |
+| ElevenLabs voice ID | `config.yaml` → `tts.elevenlabs.voice_id` |
+| ElevenLabs model ID | `config.yaml` → `tts.elevenlabs.model_id` |
+| OpenAI model | `config.yaml` → `tts.openai.model` |
+| OpenAI voice | `config.yaml` → `tts.openai.voice` |
+| Edge TTS voice | `config.yaml` → `tts.edge.voice` (OpenClaw renamed "edge" to "microsoft" — both are recognized) |
+| TTS assets | `~/.hermes/tts/` (file copy) |
+
+### Messaging platforms
+
+| Platform | OpenClaw config path | Hermes `.env` variable | Notes |
+|----------|---------------------|----------------------|-------|
+| Telegram | `channels.telegram.botToken` or `.accounts.default.botToken` | `TELEGRAM_BOT_TOKEN` | Token can be string or [SecretRef](#secretref-handling). Both flat and accounts layout supported. |
+| Telegram | `credentials/telegram-default-allowFrom.json` | `TELEGRAM_ALLOWED_USERS` | Comma-joined from `allowFrom[]` array |
+| Discord | `channels.discord.token` or `.accounts.default.token` | `DISCORD_BOT_TOKEN` | |
+| Discord | `channels.discord.allowFrom` or `.accounts.default.allowFrom` | `DISCORD_ALLOWED_USERS` | |
+| Slack | `channels.slack.botToken` or `.accounts.default.botToken` | `SLACK_BOT_TOKEN` | |
+| Slack | `channels.slack.appToken` or `.accounts.default.appToken` | `SLACK_APP_TOKEN` | |
+| Slack | `channels.slack.allowFrom` or `.accounts.default.allowFrom` | `SLACK_ALLOWED_USERS` | |
+| WhatsApp | `channels.whatsapp.allowFrom` or `.accounts.default.allowFrom` | `WHATSAPP_ALLOWED_USERS` | Auth via Baileys QR pairing — requires re-pairing after migration |
+| Signal | `channels.signal.account` or `.accounts.default.account` | `SIGNAL_ACCOUNT` | |
+| Signal | `channels.signal.httpUrl` or `.accounts.default.httpUrl` | `SIGNAL_HTTP_URL` | |
+| Signal | `channels.signal.allowFrom` or `.accounts.default.allowFrom` | `SIGNAL_ALLOWED_USERS` | |
+| Matrix | `channels.matrix.accessToken` or `.accounts.default.accessToken` | `MATRIX_ACCESS_TOKEN` | Uses `accessToken` (not `botToken`) |
+| Mattermost | `channels.mattermost.botToken` or `.accounts.default.botToken` | `MATTERMOST_BOT_TOKEN` | |
+
+### Other config
+
+| What | OpenClaw path | Hermes path | Notes |
+|------|-------------|-------------|-------|
+| Approval mode | `approvals.exec.mode` | `config.yaml` → `approvals.mode` | "auto"→"off", "always"→"manual", "smart"→"smart" |
+| Command allowlist | `exec-approvals.json` | `config.yaml` → `command_allowlist` | Patterns merged and deduped |
+| Browser CDP URL | `browser.cdpUrl` | `config.yaml` → `browser.cdp_url` | |
+| Browser headless | `browser.headless` | `config.yaml` → `browser.headless` | |
+| Brave search key | `tools.web.search.brave.apiKey` | `.env` → `BRAVE_API_KEY` | Requires `--migrate-secrets` |
+| Gateway auth token | `gateway.auth.token` | `.env` → `HERMES_GATEWAY_TOKEN` | Requires `--migrate-secrets` |
+| Working directory | `agents.defaults.workspace` | `config.yaml` → `terminal.cwd` | Legacy migrations may still emit `MESSAGING_CWD` as a compatibility fallback |
+
+### Archived (no direct Hermes equivalent)
+
+These are saved to `~/.hermes/migration/openclaw/<timestamp>/archive/` for manual review:
+
+| What | Archive file | How to recreate in Hermes |
+|------|-------------|--------------------------|
+| `IDENTITY.md` | `archive/workspace/IDENTITY.md` | Merge into `SOUL.md` |
+| `TOOLS.md` | `archive/workspace/TOOLS.md` | Hermes has built-in tool instructions |
+| `HEARTBEAT.md` | `archive/workspace/HEARTBEAT.md` | Use cron jobs for periodic tasks |
+| `BOOTSTRAP.md` | `archive/workspace/BOOTSTRAP.md` | Use context files or skills |
+| Cron jobs | `archive/cron-config.json` | Recreate with `hermes cron create` |
+| Plugins | `archive/plugins-config.json` | See [plugins guide](/user-guide/features/hooks) |
+| Hooks/webhooks | `archive/hooks-config.json` | Use `hermes webhook` or gateway hooks |
+| Memory backend | `archive/memory-backend-config.json` | Configure via `hermes honcho` |
+| Skills registry | `archive/skills-registry-config.json` | Use `hermes skills config` |
+| UI/identity | `archive/ui-identity-config.json` | Use `/skin` command |
+| Logging | `archive/logging-diagnostics-config.json` | Set in `config.yaml` logging section |
+| Multi-agent list | `archive/agents-list.json` | Use Hermes profiles |
+| Channel bindings | `archive/bindings.json` | Manual setup per platform |
+| Complex channels | `archive/channels-deep-config.json` | Manual platform config |
+
+## API key resolution
+
+When `--migrate-secrets` is enabled, API keys are collected from **four sources** in priority order:
+
+1. **Config values** — `models.providers.*.apiKey` and TTS provider keys in `openclaw.json`
+2. **Environment file** — `~/.openclaw/.env` (keys like `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
+3. **Config env sub-object** — `openclaw.json` → `"env"` or `"env"."vars"` (some setups store keys here instead of a separate `.env` file)
+4. **Auth profiles** — `~/.openclaw/agents/main/agent/auth-profiles.json` (per-agent credentials)
+
+Config values take priority. Each subsequent source fills any remaining gaps.
+
+### Supported key targets
+
+`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `MINIMAX_API_KEY`, `ELEVENLABS_API_KEY`, `TELEGRAM_BOT_TOKEN`, `VOICE_TOOLS_OPENAI_KEY`
+
+Keys not in this allowlist are never copied.
+
+## SecretRef handling
+
+OpenClaw config values for tokens and API keys can be in three formats:
+
+```json
+// Plain string
+"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }
+
+// Environment template
+"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }
+
+// SecretRef object
+"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }
+```
+
+The migration resolves all three formats. For env templates and SecretRef objects with `source: "env"`, it looks up the value in `~/.openclaw/.env` and the `openclaw.json` env sub-object. SecretRef objects with `source: "file"` or `source: "exec"` can't be resolved automatically — the migration warns about these, and those values must be added to Hermes manually via `hermes config set`.
+
+## After migration
+
+1. **Check the migration report** — printed on completion with counts of migrated, skipped, and conflicting items.
+
+2. **Review archived files** — anything in `~/.hermes/migration/openclaw/<timestamp>/archive/` needs manual attention.
+
+3. **Start a new session** — imported skills and memory entries take effect in new sessions, not the current one.
+
+4. **Verify API keys** — run `hermes status` to check provider authentication.
+
+5. **Test messaging** — if you migrated platform tokens, restart the gateway: `systemctl --user restart hermes-gateway`
+
+6. **Check session archives** — review archived advanced settings; idle and daily reset timers are intentionally not imported.
+
+7. **Re-pair WhatsApp** — WhatsApp uses QR code pairing (Baileys), not token migration. Run `hermes whatsapp` to pair.
+
+8. **Archive cleanup** — after confirming everything works, run `hermes claw cleanup` to rename leftover OpenClaw directories to `.pre-migration/` (prevents state confusion).
+
+## Troubleshooting
+
+### "OpenClaw directory not found"
+
+The migration checks `~/.openclaw/`, then `~/.clawdbot/`, then `~/.moltbot/`. If your installation is elsewhere, use `--source /path/to/your/openclaw`.
+
+### "No provider API keys found"
+
+Keys might be stored in several places depending on your OpenClaw version: inline in `openclaw.json` under `models.providers.*.apiKey`, in `~/.openclaw/.env`, in the `openclaw.json` `"env"` sub-object, or in `agents/main/agent/auth-profiles.json`. The migration checks all four. If keys use `source: "file"` or `source: "exec"` SecretRefs, they can't be resolved automatically — add them via `hermes config set`.
+
+### Skills not appearing after migration
+
+Imported skills land in `~/.hermes/skills/openclaw-imports/`. Start a new session for them to take effect, or run `/skills` to verify they're loaded.
+
+### TTS voice not migrated
+
+OpenClaw stores TTS settings in two places: `messages.tts.providers.*` and the top-level `talk` config. The migration checks both. If your voice ID was set via the OpenClaw UI (stored in a different path), you may need to set it manually: `hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID`.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/minimax-oauth.md

@@ -0,0 +1,226 @@
+---
+sidebar_position: 15
+title: "MiniMax OAuth"
+description: "Log into MiniMax via browser OAuth and use MiniMax-M2.7 models in Hermes Agent — no API key required"
+---
+
+# MiniMax OAuth
+
+Hermes Agent supports **MiniMax** through a browser-based OAuth login flow, using the same credentials as the [MiniMax portal](https://www.minimax.io). No API key or credit card is required — log in once and Hermes automatically refreshes your session.
+
+The transport reuses the `anthropic_messages` adapter (MiniMax exposes an Anthropic Messages-compatible endpoint at `/anthropic`), so all existing tool-calling, streaming, and context features work without any adapter changes.
+
+## Overview
+
+| Item | Value |
+|------|-------|
+| Provider ID | `minimax-oauth` |
+| Display name | MiniMax (OAuth) |
+| Auth type | Browser OAuth (PKCE redirect flow) |
+| Transport | Anthropic Messages-compatible (`anthropic_messages`) |
+| Models | `MiniMax-M2.7`, `MiniMax-M2.7-highspeed` |
+| Global endpoint | `https://api.minimax.io/anthropic` |
+| China endpoint | `https://api.minimaxi.com/anthropic` |
+| Requires env var | No (`MINIMAX_API_KEY` is **not** used for this provider) |
+
+## Prerequisites
+
+- Python 3.9+
+- Hermes Agent installed
+- A MiniMax account at [minimax.io](https://www.minimax.io) (global) or [minimaxi.com](https://www.minimaxi.com) (China)
+- A browser available on the local machine (or use `--no-browser` for remote sessions)
+
+## Quick Start
+
+```bash
+# Launch the provider and model picker
+hermes model
+# → Select "MiniMax (OAuth)" from the provider list
+# → Hermes opens your browser to the MiniMax authorization page
+# → Approve access in the browser
+# → Select a model (MiniMax-M2.7 or MiniMax-M2.7-highspeed)
+# → Start chatting
+
+hermes
+```
+
+After the first login, credentials are stored under `~/.hermes/auth.json` and are refreshed automatically before each session.
+
+## Logging In Manually
+
+You can trigger a login without going through the model picker:
+
+```bash
+hermes auth add minimax-oauth
+```
+
+### China region
+
+If your account is on the China platform (`minimaxi.com`), use the API-key-based `minimax-cn` provider instead — `minimax-cn` is registered with `auth_type="api_key"` only (no OAuth flow). Configure `MINIMAX_CN_API_KEY` (and optionally `MINIMAX_CN_BASE_URL`) directly:
+
+```bash
+echo 'MINIMAX_CN_API_KEY=your-key' >> ~/.hermes/.env
+```
+
+### Remote / headless sessions
+
+On servers or containers where no browser is available:
+
+```bash
+hermes auth add minimax-oauth --no-browser
+```
+
+Hermes will print the verification URL and user code — open the URL on any device and enter the code when prompted.
+
+## The OAuth Flow
+
+Hermes implements a PKCE browser OAuth flow against the MiniMax OAuth endpoints:
+
+1. Hermes generates a PKCE verifier / challenge pair and a random state value.
+2. It POSTs to `{base_url}/oauth/code` with the challenge and receives a `user_code` and `verification_uri`.
+3. Your browser opens `verification_uri`. If prompted, enter the `user_code`.
+4. Hermes polls `{base_url}/oauth/token` until the token arrives (or the deadline passes).
+5. Tokens (`access_token`, `refresh_token`, expiry) are saved to `~/.hermes/auth.json` under the `minimax-oauth` key.
+
+Token refresh (standard OAuth `refresh_token` grant) runs automatically at each session start when the access token is within 60 seconds of expiry.
+
+## Checking Login Status
+
+```bash
+hermes doctor
+```
+
+The `◆ Auth Providers` section will show:
+
+```
+✓ MiniMax OAuth  (logged in, region=global)
+```
+
+or, if not logged in:
+
+```
+⚠ MiniMax OAuth  (not logged in)
+```
+
+## Switching Models
+
+```bash
+hermes model
+# → Select "MiniMax (OAuth)"
+# → Pick from the model list
+```
+
+Or set the model directly:
+
+```bash
+hermes config set model.default MiniMax-M2.7
+hermes config set model.provider minimax-oauth
+```
+
+## Configuration Reference
+
+After login, `~/.hermes/config.yaml` will contain entries similar to:
+
+```yaml
+model:
+  default: MiniMax-M2.7
+  provider: minimax-oauth
+  base_url: https://api.minimax.io/anthropic
+```
+
+### Region endpoints
+
+| Provider id | Portal | Inference endpoint |
+|-------------|--------|-------------------|
+| `minimax-oauth` (global) | `https://api.minimax.io` | `https://api.minimax.io/anthropic` |
+| `minimax-cn` (China) | `https://api.minimaxi.com` | `https://api.minimaxi.com/anthropic` |
+
+### Provider aliases
+
+All of the following resolve to `minimax-oauth`:
+
+```bash
+hermes --provider minimax-oauth    # canonical
+hermes --provider minimax-portal   # alias
+hermes --provider minimax-global   # alias
+hermes --provider minimax_oauth    # alias (underscore form)
+```
+
+## Environment Variables
+
+The `minimax-oauth` provider does **not** use `MINIMAX_API_KEY` or `MINIMAX_BASE_URL`. Those variables are for the API-key-based `minimax` and `minimax-cn` providers only.
+
+| Variable | Effect |
+|----------|--------|
+| `MINIMAX_API_KEY` | Used by `minimax` provider only — ignored for `minimax-oauth` |
+| `MINIMAX_CN_API_KEY` | Used by `minimax-cn` provider only — ignored for `minimax-oauth` |
+
+To use `minimax-oauth` as the active provider, set `model.provider: minimax-oauth` in `config.yaml` (use `hermes setup` for the guided flow), or pass `--provider minimax-oauth` for a single invocation:
+
+```bash
+hermes --provider minimax-oauth
+```
+
+## Models
+
+| Model | Best for |
+|-------|----------|
+| `MiniMax-M2.7` | Long-context reasoning, complex tool-calling |
+| `MiniMax-M2.7-highspeed` | Lower latency, lighter tasks, auxiliary calls |
+
+Both models support up to 200,000 tokens of context.
+
+`MiniMax-M2.7` is also used automatically as the auxiliary model for vision and delegation tasks when `minimax-oauth` is the primary provider.
+
+## Troubleshooting
+
+### Token expired — not re-logging in automatically
+
+Hermes refreshes the token on every session start if it is within 60 seconds of expiry. If the access token is already expired (for example, after a long offline period), the refresh happens automatically on the next request. If refresh fails with `refresh_token_reused` or `invalid_grant`, Hermes marks the session as requiring re-login.
+
+When the refresh failure is terminal (HTTP 4xx, `invalid_grant`, revoked grant, etc.), Hermes marks the refresh token as dead and quarantines it locally so it doesn't keep replaying the doomed exchange. The agent surfaces a single "re-authentication required" message and stays out of the way until you log in again.
+
+**Fix:** run `hermes auth add minimax-oauth` again to start a fresh login. The quarantine clears on the next successful exchange.
+
+### Authorization timed out
+
+The device-code flow has a finite expiry window. If you don't approve the login in time, Hermes raises a timeout error.
+
+**Fix:** re-run `hermes auth add minimax-oauth` (or `hermes model`). The flow starts fresh.
+
+### State mismatch (possible CSRF)
+
+Hermes detected that the `state` value returned by the authorization server does not match what it sent.
+
+**Fix:** re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response.
+
+### Logging in from a remote server
+
+If `hermes` cannot open a browser window, use `--no-browser`:
+
+```bash
+hermes auth add minimax-oauth --no-browser
+```
+
+Hermes prints the URL and code. Open the URL on any device and complete the flow there.
+
+### "Not logged into MiniMax OAuth" error at runtime
+
+The auth store has no credentials for `minimax-oauth`. You have not logged in yet, or the credential file was deleted.
+
+**Fix:** run `hermes model` and select MiniMax (OAuth), or run `hermes auth add minimax-oauth`.
+
+## Logging Out
+
+To remove stored MiniMax OAuth credentials:
+
+```bash
+hermes auth logout minimax-oauth
+```
+
+## See Also
+
+- [AI Providers reference](../integrations/providers.md)
+- [Environment Variables](../reference/environment-variables.md)
+- [Configuration](../user-guide/configuration.md)
+- [hermes doctor](../reference/cli-commands.md)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/oauth-over-ssh.md

@@ -0,0 +1,172 @@
+---
+sidebar_position: 17
+title: "OAuth over SSH / Remote Hosts"
+description: "How to complete browser-based OAuth (Spotify, MCP servers) when Hermes runs on a remote machine, container, or behind a jump box"
+---
+
+# OAuth over SSH / Remote Hosts
+
+Some Hermes providers — **Spotify** and **remote MCP servers** (Linear, Sentry, Atlassian, Asana, Figma, …) — use a *loopback redirect* OAuth flow. The auth server redirects your browser to `http://127.0.0.1:<port>/callback` so a tiny HTTP listener started by Hermes can grab the authorization code.
+
+This works perfectly when Hermes and your browser are on the same machine. It breaks the moment they aren't: your laptop's browser tries to reach `127.0.0.1` on **your laptop**, but the listener is bound to `127.0.0.1` on **the remote server**.
+
+The fix is a one-line SSH local-forward. For MCP servers on an interactive terminal, you can often paste the redirect URL back instead (no tunnel).
+
+**xAI Grok OAuth (`xai-oauth`) uses OAuth device code**, not a loopback callback — open the printed verification URL in any browser and Hermes polls until approval. No SSH tunnel is required. See [xAI Grok OAuth](./xai-grok-oauth.md).
+
+## TL;DR
+
+```bash
+# On your local machine (laptop), in a separate terminal:
+ssh -N -L 43827:127.0.0.1:43827 user@remote-host
+
+# In your existing SSH session on the remote machine:
+hermes auth spotify --no-browser
+# → Hermes prints an authorize URL. Open it in a browser on your laptop.
+# → Your browser redirects to 127.0.0.1:43827/callback, the tunnel forwards
+#   the request to the remote listener, login completes.
+```
+
+Hermes prints the exact port it bound to on the `Waiting for callback on ...` line — copy it from there. Spotify defaults to port `43827`.
+
+## Which Providers Need This
+
+| Provider | Loopback port | Tunnel needed? |
+|----------|---------------|----------------|
+| Spotify | `43827` (default) | Yes, when Hermes is remote |
+| MCP servers (`auth: oauth`) | auto-picked per server | Yes, when Hermes is remote (or paste redirect URL) |
+| `xai-oauth` (Grok SuperGrok) | n/a | No — device code flow |
+| `anthropic` (Claude Pro/Max) | n/a | No — paste-the-code flow |
+| `openai-codex` (ChatGPT Plus/Pro) | n/a | No — device code flow |
+| `minimax`, `nous-portal` | n/a | No — device code flow |
+| `openrouter` (`hermes auth add openrouter --type oauth`) | OS-assigned, local only | No — over SSH Hermes switches to OpenRouter's headless flow and asks you to paste the code shown in the browser |
+
+If your provider isn't in the table, you don't need a tunnel.
+
+## MCP Servers
+
+**Desktop Skills → MCP:** the native app receives the callback on your computer
+and relays it to the selected connection and profile, so this flow does not need
+an SSH callback tunnel or `dashboard.public_url`. Tokens stay on the owning
+backend profile. Leaving the MCP tab or changing its scope cancels pending
+sign-in. If Desktop asks you to update the backend, update it before retrying;
+it does not fall back to a remote HTTP callback. The terminal workflows below
+are unchanged.
+
+Remote MCP servers (Linear, Sentry, Atlassian, Asana, Figma, etc.) use the same loopback redirect flow. Hermes auto-picks a free port per server and prints the authorize URL when the OAuth flow kicks off — either at startup (when a new server appears in `mcp_servers:`) or when you run `hermes mcp login <server>`.
+
+You have two ways to complete it from a remote host:
+
+**Option 1 — paste the redirect URL back (no setup, works anywhere).** On an interactive terminal, Hermes prompts you to paste the redirect URL alongside running the local listener. After approving in your browser, the redirect to `http://127.0.0.1:<port>/callback` will show a connection error — that's expected. Copy the **full URL from the browser's address bar** and paste it at the Hermes prompt:
+
+```
+  MCP OAuth: authorization required.
+  Open this URL in your browser:
+
+    https://mcp.linear.app/authorize?response_type=code&...
+
+  Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter:
+> https://mcp.linear.app/callback?code=abc123&state=xyz
+  Got authorization code from paste — completing flow.
+```
+
+A bare `?code=...&state=...` query string is accepted too. This works for any MCP server with `auth: oauth` and requires no SSH config changes.
+
+**Option 2 — SSH port forward (same as Spotify).** Hermes prints the exact port it bound to in the SSH-session hint. Open a separate terminal on your laptop:
+
+```bash
+ssh -N -L <port>:127.0.0.1:<port> user@remote-host
+```
+
+Then open the authorize URL in your browser as normal; the redirect tunnels through and the listener picks it up. Use this when you need the flow to complete unattended (e.g. scripted re-auth where you can't paste interactively).
+
+**Pitfall — the 30s config-reload race.** If you edit `~/.hermes/config.yaml` to add an OAuth MCP server from inside a running Hermes session, the CLI auto-reloads MCP connections with a 30s timeout. That's not enough time to complete an interactive OAuth flow, and the reload will give up. Use `hermes mcp login <server>` from a fresh terminal instead — it has no such cap and waits the full 5 min for you to paste back.
+
+## Why the listener can't just bind 0.0.0.0
+
+Spotify and most MCP OAuth servers validate the `redirect_uri` parameter against an allowlist. Both require the loopback form (`http://127.0.0.1:<exact-port>/callback`). Binding the listener to `0.0.0.0` or a different port would cause the auth server to reject the request as a redirect_uri mismatch. The SSH tunnel keeps the loopback URI intact end-to-end.
+
+## Step-by-step: single SSH hop
+
+### 1. Start the tunnel from your local machine
+
+```bash
+# Spotify (port 43827)
+ssh -N -L 43827:127.0.0.1:43827 user@remote-host
+```
+
+`-N` means "don't open a remote shell, just hold the tunnel open." Keep this terminal running for the duration of the login.
+
+### 2. In a separate SSH session, run the auth command
+
+```bash
+ssh user@remote-host
+hermes auth spotify --no-browser
+```
+
+Hermes detects the SSH session, skips the browser auto-open, and prints an authorize URL plus a `Waiting for callback on http://127.0.0.1:<port>/callback` line.
+
+### 3. Open the URL in your local browser
+
+Copy the authorize URL from the remote terminal and paste it into the browser on your laptop. Approve the consent screen. The auth server redirects to `http://127.0.0.1:<port>/callback`. Your browser hits the tunnel, the request is forwarded to the remote listener, and Hermes prints `Login successful!`.
+
+You can tear down the tunnel (Ctrl+C in the first terminal) once you see the success line.
+
+## Step-by-step: through a jump box
+
+If you reach Hermes through a bastion / jump host, use SSH's built-in `-J` (ProxyJump):
+
+```bash
+ssh -N -L 43827:127.0.0.1:43827 -J jump-user@jump-host user@final-host
+```
+
+This chains a SSH connection through the jump host without putting the loopback port on the jump box itself. The local `127.0.0.1:43827` on your laptop tunnels straight through to `127.0.0.1:43827` on the final remote host.
+
+For older OpenSSH that doesn't support `-J`, the long form is:
+
+```bash
+ssh -N \
+    -o "ProxyCommand=ssh -W %h:%p jump-user@jump-host" \
+    -L 43827:127.0.0.1:43827 \
+    user@final-host
+```
+
+## Mosh, tmux, ssh ControlMaster
+
+The tunnel is a property of the underlying SSH connection. If you're running Hermes inside `tmux` over a mosh session, the mosh roaming doesn't carry the `-L` forwarding. Open a *separate* plain SSH session **only** for the `-L` tunnel — that's the connection that has to stay alive during the auth flow. Your interactive mosh/tmux session can keep running Hermes normally.
+
+If you use `ssh -o ControlMaster=auto`, port forwards on a multiplexed connection share the master's lifetime. Restart the master if the tunnel doesn't come up:
+
+```bash
+ssh -O exit user@remote-host
+ssh -N -L 43827:127.0.0.1:43827 user@remote-host
+```
+
+## Troubleshooting
+
+### `bind [127.0.0.1]:43827: Address already in use`
+
+Something on your laptop is already using that port. Either the previous tunnel didn't shut down cleanly, or a local Hermes is also listening on it. Find and kill the offender:
+
+```bash
+# macOS / Linux
+lsof -iTCP:43827 -sTCP:LISTEN
+kill <PID>
+```
+
+Then retry the `ssh -L` command.
+
+### Authorization timed out waiting for the local callback
+
+The redirect never made it back to the remote listener. Check the tunnel is still alive (`ssh -N` doesn't show output, so look at the terminal you started it from), confirm you used the port from the latest `Waiting for callback on ...` line (Hermes may auto-bump if the preferred port is busy), restart the tunnel if needed, and re-run the auth command.
+
+### Tokens land in the wrong `~/.hermes`
+
+The tokens are written under the Linux user that ran `hermes auth add ...`. If your gateway / systemd service runs as a different user (e.g. `root` or a dedicated `hermes` user), authenticate as **that** user so the tokens land in their `~/.hermes/auth.json`. `sudo -u hermes -i` or equivalent.
+
+## See Also
+
+- [xAI Grok OAuth](./xai-grok-oauth.md) — device code; no SSH tunnel
+- [Spotify (`Running over SSH`)](../user-guide/features/spotify.md#running-over-ssh--in-a-headless-environment)
+- [Native MCP client (OAuth section)](../user-guide/features/mcp.md#oauth-authenticated-http-servers)
+- [SSH `-J` / ProxyJump (man page)](https://man.openbsd.org/ssh#J)