fix(skills): correct TTS/STT providers, add missing platforms/commands in hermes-agent skill

Fixes verified via 5-container parallel testing against v0.8.0 codebase.

Critical fixes:
- TTS providers: replace nonexistent kokoro/fish with actual minimax/mistral/neutts
- STT providers: add missing mistral (Voxtral Transcribe)
- Testing section: remove `source venv/bin/activate` (no venv dir in project)

Expanded coverage:
- Provider table: 13 → 22 entries (add Gemini, xAI, Xiaomi, Qwen OAuth, MiniMax CN, etc.)
- Platform list: add BlueBubbles (iMessage) and Weixin (WeChat), clarify Open WebUI
- Slash commands: add 14 undocumented commands (/approve, /deny, /branch, /fast, etc.)
- Toolsets: add 4 missing (messaging, search, todo, rl)
- Troubleshooting: expand from 6 to 10 sections with practical deployment fixes
  (Copilot OAuth 403, gateway linger, WSL2 systemd, Discord intents, etc.)

Minor fixes:
- agent/ directory description expanded
- delegation config keys completed
- /restart noted as gateway-only
- hermes honcho noted as plugin-dependent
This commit is contained in:
Haoqing Wang 2026-04-13 13:45:29 +08:00 committed by Teknium
parent 397eae5d93
commit 8e0ae66520

View file

@ -19,7 +19,7 @@ What makes Hermes different:
- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment. - **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment.
- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works. - **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works.
- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 8+ other platforms with full tool access, not just chat. - **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 10+ other platforms with full tool access, not just chat.
- **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically. - **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically.
- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory. - **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
- **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem. - **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem.
@ -148,7 +148,7 @@ hermes gateway status Check status
hermes gateway setup Configure platforms hermes gateway setup Configure platforms
``` ```
Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, API Server, Webhooks, Open WebUI. Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, BlueBubbles (iMessage), Weixin (WeChat), API Server, Webhooks. Open WebUI connects via the API Server adapter.
Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
@ -215,7 +215,7 @@ hermes insights [--days N] Usage analytics
hermes update Update to latest version hermes update Update to latest version
hermes pairing list/approve/revoke DM authorization hermes pairing list/approve/revoke DM authorization
hermes plugins list/install/remove Plugin management hermes plugins list/install/remove Plugin management
hermes honcho setup/status Honcho memory integration hermes honcho setup/status Honcho memory integration (requires honcho plugin)
hermes memory setup/status/off Memory provider config hermes memory setup/status/off Memory provider config
hermes completion bash|zsh Shell completions hermes completion bash|zsh Shell completions
hermes acp ACP server (IDE integration) hermes acp ACP server (IDE integration)
@ -269,6 +269,28 @@ Type these during an interactive chat session.
/plugins List plugins (CLI) /plugins List plugins (CLI)
``` ```
### Gateway
```
/approve Approve a pending command (gateway)
/deny Deny a pending command (gateway)
/restart Restart gateway (gateway)
/sethome Set current chat as home channel (gateway)
/update Update Hermes to latest (gateway)
/platforms (/gateway) Show platform connection status (gateway)
```
### Utility
```
/branch (/fork) Branch the current session
/btw Ephemeral side question (doesn't interrupt main task)
/fast Toggle priority/fast processing
/browser Open CDP browser connection
/history Show conversation history (CLI)
/save Save conversation to file (CLI)
/paste Attach clipboard image (CLI)
/image Attach local image file (CLI)
```
### Info ### Info
``` ```
/help Show commands /help Show commands
@ -311,11 +333,11 @@ Edit with `hermes config edit` or `hermes config set section.key value`.
| `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) | | `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) |
| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) | | `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
| `display` | `skin`, `tool_progress`, `show_reasoning`, `show_cost` | | `display` | `skin`, `tool_progress`, `show_reasoning`, `show_cost` |
| `stt` | `enabled`, `provider` (local/groq/openai) | | `stt` | `enabled`, `provider` (local/groq/openai/mistral) |
| `tts` | `provider` (edge/elevenlabs/openai/kokoro/fish) | | `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts) |
| `memory` | `memory_enabled`, `user_profile_enabled`, `provider` | | `memory` | `memory_enabled`, `user_profile_enabled`, `provider` |
| `security` | `tirith_enabled`, `website_blocklist` | | `security` | `tirith_enabled`, `website_blocklist` |
| `delegation` | `model`, `provider`, `max_iterations` (50) | | `delegation` | `model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort` |
| `smart_model_routing` | `enabled`, `cheap_model` | | `smart_model_routing` | `enabled`, `cheap_model` |
| `checkpoints` | `enabled`, `max_snapshots` (50) | | `checkpoints` | `enabled`, `max_snapshots` (50) |
@ -323,7 +345,7 @@ Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/con
### Providers ### Providers
18 providers supported. Set via `hermes model` or `hermes setup`. 20+ providers supported. Set via `hermes model` or `hermes setup`.
| Provider | Auth | Key env var | | Provider | Auth | Key env var |
|----------|------|-------------| |----------|------|-------------|
@ -332,16 +354,23 @@ Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/con
| Nous Portal | OAuth | `hermes login --provider nous` | | Nous Portal | OAuth | `hermes login --provider nous` |
| OpenAI Codex | OAuth | `hermes login --provider openai-codex` | | OpenAI Codex | OAuth | `hermes login --provider openai-codex` |
| GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` | | GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` |
| Google Gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
| DeepSeek | API key | `DEEPSEEK_API_KEY` | | DeepSeek | API key | `DEEPSEEK_API_KEY` |
| xAI / Grok | API key | `XAI_API_KEY` |
| Hugging Face | Token | `HF_TOKEN` | | Hugging Face | Token | `HF_TOKEN` |
| Z.AI / GLM | API key | `GLM_API_KEY` | | Z.AI / GLM | API key | `GLM_API_KEY` |
| MiniMax | API key | `MINIMAX_API_KEY` | | MiniMax | API key | `MINIMAX_API_KEY` |
| MiniMax CN | API key | `MINIMAX_CN_API_KEY` |
| Kimi / Moonshot | API key | `KIMI_API_KEY` | | Kimi / Moonshot | API key | `KIMI_API_KEY` |
| Alibaba / DashScope | API key | `DASHSCOPE_API_KEY` | | Alibaba / DashScope | API key | `DASHSCOPE_API_KEY` |
| Xiaomi MiMo | API key | `XIAOMI_API_KEY` |
| Kilo Code | API key | `KILOCODE_API_KEY` | | Kilo Code | API key | `KILOCODE_API_KEY` |
| AI Gateway (Vercel) | API key | `AI_GATEWAY_API_KEY` |
| OpenCode Zen | API key | `OPENCODE_ZEN_API_KEY` |
| OpenCode Go | API key | `OPENCODE_GO_API_KEY` |
| Qwen OAuth | OAuth | `hermes login --provider qwen-oauth` |
| Custom endpoint | Config | `model.base_url` + `model.api_key` in config.yaml | | Custom endpoint | Config | `model.base_url` + `model.api_key` in config.yaml |
| GitHub Copilot ACP | External | `COPILOT_CLI_PATH` or Copilot CLI |
Plus: AI Gateway, OpenCode Zen, OpenCode Go, MiniMax CN, GitHub Copilot ACP.
Full provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers Full provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers
@ -364,7 +393,10 @@ Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable
| `session_search` | Search past conversations | | `session_search` | Search past conversations |
| `delegation` | Subagent task delegation | | `delegation` | Subagent task delegation |
| `cronjob` | Scheduled task management | | `cronjob` | Scheduled task management |
| `clarify` | Ask user clarifying questions | | `messaging` | Cross-platform message sending |
| `search` | Web search only (subset of `web`) |
| `todo` | In-session task planning and tracking |
| `rl` | Reinforcement learning tools (off by default) |
| `moa` | Mixture of Agents (off by default) | | `moa` | Mixture of Agents (off by default) |
| `homeassistant` | Smart home control (off by default) | | `homeassistant` | Smart home control (off by default) |
@ -382,12 +414,13 @@ Provider priority (auto-detected):
1. **Local faster-whisper** — free, no API key: `pip install faster-whisper` 1. **Local faster-whisper** — free, no API key: `pip install faster-whisper`
2. **Groq Whisper** — free tier: set `GROQ_API_KEY` 2. **Groq Whisper** — free tier: set `GROQ_API_KEY`
3. **OpenAI Whisper** — paid: set `VOICE_TOOLS_OPENAI_KEY` 3. **OpenAI Whisper** — paid: set `VOICE_TOOLS_OPENAI_KEY`
4. **Mistral Voxtral** — set `MISTRAL_API_KEY`
Config: Config:
```yaml ```yaml
stt: stt:
enabled: true enabled: true
provider: local # local, groq, openai provider: local # local, groq, openai, mistral
local: local:
model: base # tiny, base, small, medium, large-v3 model: base # tiny, base, small, medium, large-v3
``` ```
@ -399,8 +432,9 @@ stt:
| Edge TTS | None | Yes (default) | | Edge TTS | None | Yes (default) |
| ElevenLabs | `ELEVENLABS_API_KEY` | Free tier | | ElevenLabs | `ELEVENLABS_API_KEY` | Free tier |
| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid | | OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid |
| Kokoro (local) | None | Free | | MiniMax | `MINIMAX_API_KEY` | Paid |
| Fish Audio | `FISH_AUDIO_API_KEY` | Free tier | | Mistral (Voxtral) | `MISTRAL_API_KEY` | Paid |
| NeuTTS (local) | None (`pip install neutts[all]` + `espeak-ng`) | Free |
Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`. Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`.
@ -492,7 +526,7 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305
### Voice not working ### Voice not working
1. Check `stt.enabled: true` in config.yaml 1. Check `stt.enabled: true` in config.yaml
2. Verify provider: `pip install faster-whisper` or set API key 2. Verify provider: `pip install faster-whisper` or set API key
3. Restart gateway: `/restart` 3. In gateway: `/restart`. In CLI: exit and relaunch.
### Tool not available ### Tool not available
1. `hermes tools` — check if toolset is enabled for your platform 1. `hermes tools` — check if toolset is enabled for your platform
@ -503,10 +537,11 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305
1. `hermes doctor` — check config and dependencies 1. `hermes doctor` — check config and dependencies
2. `hermes login` — re-authenticate OAuth providers 2. `hermes login` — re-authenticate OAuth providers
3. Check `.env` has the right API key 3. Check `.env` has the right API key
4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.
### Changes not taking effect ### Changes not taking effect
- **Tools/skills:** `/reset` starts a new session with updated toolset - **Tools/skills:** `/reset` starts a new session with updated toolset
- **Config changes:** `/restart` reloads gateway config - **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
- **Code changes:** Restart the CLI or gateway process - **Code changes:** Restart the CLI or gateway process
### Skills not showing ### Skills not showing
@ -520,6 +555,23 @@ Check logs first:
grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20 grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
``` ```
Common gateway problems:
- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER`
- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes).
- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway`
### Platform-specific issues
- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents.
- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels.
- **Windows HTTP 400 "No models provided"**: Config file encoding issue (BOM). Ensure `config.yaml` is saved as UTF-8 without BOM.
### Auxiliary models not working
If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider:
```bash
hermes config set auxiliary.vision.provider <your_provider>
hermes config set auxiliary.vision.model <model_name>
```
--- ---
## Where to Find Things ## Where to Find Things
@ -557,7 +609,7 @@ hermes-agent/
├── toolsets.py # Toolset definitions ├── toolsets.py # Toolset definitions
├── cli.py # Interactive CLI (HermesCLI) ├── cli.py # Interactive CLI (HermesCLI)
├── hermes_state.py # SQLite session store ├── hermes_state.py # SQLite session store
├── agent/ # Prompt builder, compression, display, adapters ├── agent/ # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
├── hermes_cli/ # CLI subcommands, config, setup, commands ├── hermes_cli/ # CLI subcommands, config, setup, commands
│ ├── commands.py # Slash command registry (CommandDef) │ ├── commands.py # Slash command registry (CommandDef)
│ ├── config.py # DEFAULT_CONFIG, env var definitions │ ├── config.py # DEFAULT_CONFIG, env var definitions
@ -626,7 +678,6 @@ run_conversation():
### Testing ### Testing
```bash ```bash
source venv/bin/activate # or .venv/bin/activate
python -m pytest tests/ -o 'addopts=' -q # Full suite python -m pytest tests/ -o 'addopts=' -q # Full suite
python -m pytest tests/tools/ -q # Specific area python -m pytest tests/tools/ -q # Specific area
``` ```