mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
docs: clarify hermes model vs /model — two commands, two purposes (#10276)
Users are confused about the difference between `hermes model` (terminal command for full provider setup) and `/model` (session command for switching between already-configured providers). This distinction was not documented anywhere. Changes across 4 doc pages: - cli-commands.md: Added warning callout explaining the difference, added --global flag docs, added 'only see OpenRouter models?' info box - slash-commands.md: Added notes on both TUI and messaging /model entries that /model only switches between configured providers - providers.md: Added 'Two Commands for Model Management' comparison table near top of page, added warning callout in switching section - faq.md: Added new FAQ entry '/model only shows one provider' with quick reference table Prompted by user feedback in Discord — new users consistently hit this confusion when trying to add providers from inside a session.
This commit is contained in:
Teknium
GitHub
parent
33ae403890
commit
4da598b48a
4 changed files with 71 additions and 7 deletions
|
|
@ -109,22 +109,31 @@ hermes chat --worktree -q "Review this repo and open a PR"
|
|||
|
||||
## `hermes model`
|
||||
|
||||
Interactive provider + model selector.
|
||||
Interactive provider + model selector. **This is the command for adding new providers, setting up API keys, and running OAuth flows.** Run it from your terminal — not from inside an active Hermes chat session.
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
Use this when you want to:
|
||||
- switch default providers
|
||||
- log into OAuth-backed providers during model selection
|
||||
- **add a new provider** (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.)
|
||||
- log into OAuth-backed providers (Anthropic, Copilot, Codex, Nous Portal)
|
||||
- enter or update API keys
|
||||
- pick from provider-specific model lists
|
||||
- configure a custom/self-hosted endpoint
|
||||
- save the new default into config
|
||||
|
||||
:::warning hermes model vs /model — know the difference
|
||||
**`hermes model`** (run from your terminal, outside any Hermes session) is the **full provider setup wizard**. It can add new providers, run OAuth flows, prompt for API keys, and configure endpoints.
|
||||
|
||||
**`/model`** (typed inside an active Hermes chat session) can only **switch between providers and models you've already set up**. It cannot add new providers, run OAuth, or prompt for API keys.
|
||||
|
||||
**If you need to add a new provider:** Exit your Hermes session first (`Ctrl+C` or `/quit`), then run `hermes model` from your terminal prompt.
|
||||
:::
|
||||
|
||||
### `/model` slash command (mid-session)
|
||||
|
||||
Switch models without leaving a session:
|
||||
Switch between already-configured models without leaving a session:
|
||||
|
||||
```
|
||||
/model # Show current model and available options
|
||||
|
|
@ -136,6 +145,16 @@ Switch models without leaving a session:
|
|||
/model openrouter:anthropic/claude-sonnet-4 # Switch back to cloud
|
||||
```
|
||||
|
||||
By default, `/model` changes apply **to the current session only**. Add `--global` to persist the change to `config.yaml`:
|
||||
|
||||
```
|
||||
/model claude-sonnet-4 --global # Switch and save as new default
|
||||
```
|
||||
|
||||
:::info What if I only see OpenRouter models?
|
||||
If you've only configured OpenRouter, `/model` will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run `hermes model` from the terminal.
|
||||
:::
|
||||
|
||||
Provider and base URL changes are persisted to `config.yaml` automatically. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.
|
||||
|
||||
## `hermes gateway`
|
||||
|
|
|
|||
|
|
@ -187,6 +187,32 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri
|
|||
|
||||
### Provider & Model Issues
|
||||
|
||||
#### `/model` only shows one provider / can't switch providers
|
||||
|
||||
**Cause:** `/model` (inside a chat session) can only switch between providers you've **already configured**. If you've only set up OpenRouter, that's all `/model` will show.
|
||||
|
||||
**Solution:** Exit your session and use `hermes model` from your terminal to add new providers:
|
||||
|
||||
```bash
|
||||
# Exit the Hermes chat session first (Ctrl+C or /quit)
|
||||
|
||||
# Run the full provider setup wizard
|
||||
hermes model
|
||||
|
||||
# This lets you: add providers, run OAuth, enter API keys, configure endpoints
|
||||
```
|
||||
|
||||
After adding a new provider via `hermes model`, start a new chat session — `/model` will now show all your configured providers.
|
||||
|
||||
:::tip Quick reference
|
||||
| Want to... | Use |
|
||||
|-----------|-----|
|
||||
| Add a new provider | `hermes model` (from terminal) |
|
||||
| Enter/change API keys | `hermes model` (from terminal) |
|
||||
| Switch model mid-session | `/model <name>` (inside session) |
|
||||
| Switch to different configured provider | `/model provider:model` (inside session) |
|
||||
:::
|
||||
|
||||
#### API key not working
|
||||
|
||||
**Cause:** Key is missing, expired, incorrectly set, or for the wrong provider.
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config` | Show current configuration |
|
||||
| `/model [model-name]` | Show or change the current model. Supports: `/model claude-sonnet-4`, `/model provider:model` (switch providers), `/model custom:model` (custom endpoint), `/model custom:name:model` (named custom provider), `/model custom` (auto-detect from endpoint). Use `--global` to persist the change to config.yaml. |
|
||||
| `/model [model-name]` | Show or change the current model. Supports: `/model claude-sonnet-4`, `/model provider:model` (switch providers), `/model custom:model` (custom endpoint), `/model custom:name:model` (named custom provider), `/model custom` (auto-detect from endpoint). Use `--global` to persist the change to config.yaml. **Note:** `/model` can only switch between already-configured providers. To add a new provider, exit the session and run `hermes model` from your terminal. |
|
||||
| `/provider` | Show available providers and current provider |
|
||||
| `/personality` | Set a predefined personality |
|
||||
| `/verbose` | Cycle tool progress display: off → new → all → verbose. Can be [enabled for messaging](#notes) via config. |
|
||||
|
|
@ -124,7 +124,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
|
|||
| `/reset` | Reset conversation history. |
|
||||
| `/status` | Show session info. |
|
||||
| `/stop` | Kill all running background processes and interrupt the running agent. |
|
||||
| `/model [provider:model]` | Show or change the model. Supports provider switches (`/model zai:glm-5`), custom endpoints (`/model custom:model`), named custom providers (`/model custom:local:qwen`), and auto-detect (`/model custom`). Use `--global` to persist the change to config.yaml. |
|
||||
| `/model [provider:model]` | Show or change the model. Supports provider switches (`/model zai:glm-5`), custom endpoints (`/model custom:model`), named custom providers (`/model custom:local:qwen`), and auto-detect (`/model custom`). Use `--global` to persist the change to config.yaml. **Note:** `/model` can only switch between already-configured providers. To add a new provider or set up API keys, use `hermes model` from your terminal (outside the chat session). |
|
||||
| `/provider` | Show provider availability and auth status. |
|
||||
| `/personality [name]` | Set a personality overlay for the session. |
|
||||
| `/fast [normal\|fast\|status]` | Toggle fast mode — OpenAI Priority Processing / Anthropic Fast Mode. |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue