XuanShu API

Hermes setup guide

Connect Hermes to XuanShu API through the Anthropic (Claude) or OpenAI (Codex) channel, with a one-line script, manual install, configuration, a smoke test, rollback, and troubleshooting.

1. Prepare an API key

If you do not have an account yet, register at /register.
Create a key used only by Hermes at /keys, setting quota, expiration, and access restrictions as needed.
Store the full key securely right away; the console may show only a redacted value later. Never put it in a repository, screenshot, or chat log.

2. One-line install (recommended)

Running this prompts you to pick a channel and paste your API key; the script writes ~/.hermes/config.yaml. It needs sudo. Source is at /install/hermes.sh if you want to review it before running.

curl -fsSL https://www.xuanshuapi.com/install/hermes.sh | sudo bash

Alternative: install Hermes manuallyExpand when you want to review each command or the script is unavailable

3. Manual install

Install with pipx:

pipx install hermes-agent
hermes --version

A printed version means the install succeeded.

4. Pick a channel and write the configuration

Models change over time, so check /available-channels for what is currently available. This overwrites any existing configuration, so back it up first.

mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
model:
  default: claude-opus-4-7
  provider: xuanshu-claude
providers:
  xuanshu-claude:
    api_mode: anthropic_messages
    base_url: https://www.xuanshuapi.com
    api_key: <YOUR_API_KEY>
    default_model: claude-opus-4-7
    models:
      - claude-opus-4-7
EOF

mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
model:
  default: gpt-5.6-sol
  provider: xuanshu-codex
providers:
  xuanshu-codex:
    api_mode: codex_responses
    base_url: https://www.xuanshuapi.com/v1
    api_key: <YOUR_API_KEY>
    default_model: gpt-5.6-sol
    models:
      - gpt-5.6-sol
EOF

5. Run the minimal smoke test

From your project directory, run the command below to start Hermes and ask it anything to confirm you get a reply.

hermes

6. Success criteria

Hermes starts normally and returns a model reply; /usage shows a successful request for the selected model; and no 404, 401/403, or 429 appears. Start real project work only after all three checks pass.

7. Roll back the configuration

Back up the configuration file and clear the related environment variables in the current terminal, then start a new login shell.

mv ~/.hermes/config.yaml ~/.hermes/config.yaml.xuanshu-backup
unset ANTHROPIC_API_KEY ANTHROPIC_BASE_URL \
  OPENAI_API_KEY OPENAI_BASE_URL
exec "$SHELL" -l

8. Troubleshooting

Record the status code, request time, model ID, and the request entry in /usage first. Redact the full key before sharing logs.

Symptom	Check	Resolution
404	The Anthropic channel base_url must be exactly https://www.xuanshuapi.com (no /v1); the Codex channel must include /v1.	Fix the base_url for the channel you are using, restart Hermes, and retry.
401 / 403	Confirm api_key is the full, untruncated key and that it has not expired or been revoked.	Copy or create a new key at /keys.
Model unavailable	Use the same key to check the exact model ID and current visibility at /available-channels.	Update default and default_model; if a model is temporarily unavailable, switch to an available model on the same protocol.
429	Check balance, key limits, and concurrent requests at /usage.	Reduce concurrency and wait for the limit window to recover; use bounded backoff only for 429.
Configuration not applied	Confirm the write landed in ~/.hermes/config.yaml and that Hermes was restarted.	Restart Hermes; already-open sessions do not reload automatically after the script writes the file.
pipx not found	pipx is not installed or not on PATH.	Install pipx first (python3 -m pip install --user pipx), then reopen the terminal.