better-dsh 0.2.5 → 0.3.0

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

@@ -1,252 +0,0 @@
----
-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

@@ -1,226 +0,0 @@
----
-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

@@ -1,172 +0,0 @@
----
-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)