Updated 2026-08-05
Use an Alibaba Cloud API key in Hermes Agent
Hermes is the one tool in this series where Alibaba documents two ordinary-key protocols. The primary example uses Anthropic Messages with `api_mode: anthropic_messages` and a Base URL ending at `/apps/anthropic`. Hermes can also use the OpenAI-compatible `/compatible-mode/v1` endpoint when the Anthropic-specific mode is removed. Pick one complete route, verify it, and use `-m` to switch models without changing the credential.
1. Install Hermes and verify the active shell
Alibaba documents the Nous Research installer for macOS, Linux, and WSL2. The script installs the required runtime and dependencies. Native Windows is not supported by that path, so use WSL2 there.
Reload the shell after installation and verify the version before changing model configuration. Hermes CLI and Hermes Desktop share `~/.hermes/config.yaml`, so an edit can affect both surfaces.
curl -fsSL \
https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \
| bash
source ~/.zshrc
hermes --versionSources checked
- Alibaba Cloud Hermes Agent guide - Primary source for installation, both protocol routes, config fields, verification, and `-m` switching.
- Nous Research Hermes Agent - Upstream source for the agent, installer, and current configuration implementation.
2. Recommended route: configure Anthropic Messages
The commands below use a Beijing workspace. Replace `{WorkspaceId}` and the key, or substitute the Singapore regional hostname for a Singapore key. `model.api_mode` must be `anthropic_messages`, and the Base URL ends at `/apps/anthropic` without `/v1`.
These commands write the credential into `~/.hermes/config.yaml`. Protect the file permissions and never commit it. If your operating model requires an external secret store, validate Hermes' current credential-loading support before changing the documented flow.
hermes config set model.provider alibaba
hermes config set model.base_url \
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.7-max
chmod 600 ~/.hermes/config.yaml3. Alternative route: use OpenAI-compatible Chat Completions
Hermes can also use the OpenAI-compatible workspace endpoint. Alibaba's instruction is to replace the `/apps/anthropic` Base URL with `/compatible-mode/v1` and remove the `api_mode` setting. Without the Anthropic override, Hermes uses its standard compatible chat route.
Do not leave `api_mode: anthropic_messages` while changing only the Base URL. That mixes Anthropic request serialization with the OpenAI Chat endpoint. Edit and validate the complete `model` block as one protocol choice.
model:
default: qwen3.7-max
provider: alibaba
base_url: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
api_key: YOUR_API_KEY
# For the OpenAI-compatible route, remove api_mode: anthropic_messages.Sources checked
- Alibaba OpenAI-compatible Chat API - Primary source for the `/chat/completions` endpoint and OpenAI-compatible request contract.
4. Verify the selected protocol with a minimal Hermes request
Send one short query after configuring the provider. A normal response proves that Hermes loaded the file and that the key, host, region, model, and selected wire format work together.
When the test fails, compare `model.base_url` and `model.api_mode` first. Authentication errors point to the key, region, workspace, IP restrictions, or a missing credential; request-shape errors point to a protocol mismatch.
hermes chat -q "Reply with hermes-ok"5. Switch models for one run or change the default
Use `hermes chat -m MODEL_ID` to select another permitted model for that run. The key, workspace Base URL, and protocol remain unchanged. If the new model does not support the active protocol, the run can fail even though the previous model worked.
Use `hermes config set model.default MODEL_ID` for a persistent change. Run a minimal test again after the edit, then confirm `~/.hermes/config.yaml` still contains the intended provider and protocol values.
# One run
hermes chat -m qwen3.7-plus
# Persistent default
hermes config set model.default qwen3.7-plus
hermes chat -q "Report the active model"FAQ
Which protocol should I use first in Hermes?
Alibaba's main pay-as-you-go example uses Anthropic Messages. Start there unless Hermes Desktop or another requirement specifically needs the OpenAI-compatible endpoint.
How do I switch a Hermes model for one run?
Use `hermes chat -m MODEL_ID`, keeping the same provider, key, Base URL, and protocol.
How do I switch the persistent default?
Run `hermes config set model.default MODEL_ID`, then verify with a minimal chat request.
Can I keep api_mode: anthropic_messages with /compatible-mode/v1?
No. Alibaba says to remove the Anthropic mode when using the OpenAI-compatible Base URL. Keeping both mixes two wire contracts.
Where does Hermes store the API key?
The documented config commands write it to `~/.hermes/config.yaml`. Restrict file permissions and do not commit or share that file.
Hermes supports two valid Alibaba routes, but only one should be active at a time: Anthropic Messages with `/apps/anthropic` and `api_mode`, or OpenAI Chat with `/compatible-mode/v1` and no Anthropic override. Verify the route, then switch only the exact model ID.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.