WorkBuddy & Hermes Integration

Both the WorkBuddy desktop workspace and the Hermes agent support a custom OpenAI-compatible provider. A few configuration steps make ZBStream your unified model source — one key, every model.

Supported Integration Paths

Note

Both clients speak the OpenAI-compatible protocol only. For the Anthropic interface, see the Anthropic API guide.

Client	Configuration	Best for
WorkBuddy	Model picker → custom model (GUI)	Desktop workspace users
WorkBuddy	Edit ~/.workbuddy/models.json directly	Bulk / scripted setups
Hermes Agent	hermes config set CLI	Agents and automation workflows

WorkBuddy: Graphical Setup

Step 1: Open the model picker at the bottom and choose "Configure custom model".
Step 2: Click "+ Add model" and select "Custom" as the provider.
Step 3: Set the endpoint to https://api.zbstream.com/v1/chat/completions, paste your ZBStream API key, and enter the exact model id from /v1/models (e.g. deepseek-v4-pro).
Advanced: enable "Tool calls" or "Image input" as needed; enable "Thinking mode" for reasoning models.
The model appears in the picker immediately after saving — switch to it and start chatting.

WorkBuddy: models.json Bulk Setup

To add several models at once, edit the local config file directly: ~/.workbuddy/models.json on macOS/Linux, or C:\Users\<name>\.workbuddy\models.json on Windows. Changes hot-reload within about a second — no restart required.

The configuration stays on your machine and is never uploaded. Do not commit this file to a public repository.

{
  "models": [
    {
      "id": "deepseek-v4-pro",
      "name": "ZBStream DeepSeek Pro",
      "vendor": "ZBStream",
      "apiKey": "sk-你的_ZBStream_API_Key",
      "url": "https://api.zbstream.com/v1/chat/completions",
      "supportsToolCall": true,
      "supportsImages": false
    }
  ]
}

Hermes Agent: CLI Setup

Hermes Agent configures custom OpenAI-compatible providers through the providers.custom prefix. You can also set url and key directly in the api section of config/hermes.yaml.

# 配置 ZBStream 作为自定义 Provider
hermes config set providers.custom.base_url "https://api.zbstream.com/v1"
hermes config set providers.custom.api_key "sk-你的_ZBSTREAM_API_KEY"

# 设置默认模型
hermes config set default_model "deepseek-v4-pro"

# 重启 Hermes 后，底部模型选择器即可看到新模型

Verify & Troubleshoot

First verify the key and model with curl against https://api.zbstream.com/v1/chat/completions.
Model names are case-sensitive and must exactly match the /v1/models output.
No trailing slashes on the endpoint; for non-standard endpoints enable "Custom protocol" in WorkBuddy.
Confirm the model supports function calling before enabling "Tool calls", otherwise calls will fail.
Send one short test conversation before handing the setup to automated workflows.