English

简体中文

English

简体中文

外观

Hermes Agent Integration with 开桥 ​

Hermes Agent supports tool calling, browser automation, code execution, and file operations. Connect it to 开桥 to access models from multiple providers through one account.

This guide covers two integration options:

OptionAuthenticationBest for
OAuth plugin (recommended)Sign in and authorize in a browser, without manually creating or pasting an API KeyHermes with the OAuth PKCE plugin API
API Key custom endpointConfigure a 开桥 API Key manuallyAPI Key users or installations that cannot upgrade Hermes yet

Both options use the OpenAI-compatible Chat Completions protocol at https://openqiao.com/api/v1. OAuth is an authorization method, not free access; requests are billed to the account and billing option selected during authorization.

For OAuth integration with other agents and shared security guidance, see Sign in with OAuth PKCE.

Prerequisites ​

  • A 开桥 account.
  • Hermes Agent installed. See the official quickstart for installation. Windows users should use WSL2.
  • The OAuth plugin requires Hermes with the declarative OAuth PKCE plugin API: main must include commit 3e67877e1b or later. Update older Hermes installations first; installing the plugin alone cannot add this capability.
  • PyPI installation requires Python 3.11 or later, in the same Python environment as Hermes.
  • A browser for initial OAuth authorization. For remote installations, see Remote authorization.

Plugin Source

This guide follows the 开桥 Hermes plugin README. The plugin includes a dedicated public OAuth client and uses OAuth 2.0 Authorization Code + S256 PKCE. No client secret is required.

Option 1: OAuth Plugin (Recommended) ​

1. Install and Enable the Plugin ​

Installing from GitHub is recommended:

bash
hermes plugins install 开桥/hermes-plugin --enable
hermes gateway restart

If no Gateway is running, simply restart Hermes after installation. If your Gateway is managed by PM2 or another process manager, restart it there instead, for example with pm2 restart hermes-gateway --update-env.

Alternative Installation and Version Pinning

For reproducible installation, get a full 40-character commit from the Releases page and replace the placeholder:

bash
hermes plugins install 开桥/hermes-plugin --ref <40-character-commit> --enable

You can also install from PyPI. The following path assumes the default Hermes virtual environment; use your actual Python path for custom installations:

bash
~/.hermes/hermes-agent/venv/bin/python -m pip install openqiao-hermes-plugin
hermes plugins enable openqiao
hermes gateway restart

The plugin must be installed in the same Python environment as Hermes to be discovered. See the plugin README for filesystem provider installation.

2. Sign In and Authorize ​

bash
hermes auth add openqiao
hermes auth status openqiao

Hermes opens the 开桥 authorization page. Select your account and billing option, approve access, then return to the terminal to check authentication status.

Hermes stores access and refresh tokens in its credential pool, not in the plugin directory. The plugin's openqiao.json contains only the public OAuth client ID. Refresh token rotation is serialized through Hermes credential locks.

Protect Your Credentials

Do not paste tokens, authorization codes, or complete authentication files into chats, tickets, or repositories. The OAuth plugin does not require copying tokens into an API Key configuration.

3. Select a Model and Verify ​

Open the model selector and choose the plugin's 开桥 provider and your desired model:

bash
hermes model

Alternatively, explicitly specify the provider and full model slug to avoid reusing a previous custom endpoint configuration:

bash
hermes --provider openqiao -m google/gemini-2.5-flash-lite
hermes --provider openqiao -m anthropic/claude-sonnet-4.5

Send a short message and confirm that the model responds. To make 开桥 the default provider:

bash
hermes config set model.provider openqiao
hermes config set model.default google/gemini-2.5-flash-lite
hermes config set model.base_url https://openqiao.com/api/v1
hermes config set model.api_mode chat_completions

hermes -z "Reply with exactly: OK" --safe-mode

Successful login confirms authorization only; an actual model response verifies that inference works.

4. Switch Models and Understand the Catalog ​

In a chat or messaging bot already using 开桥, enter:

text
/model z-ai/glm-5.3-flashx

openqiao is the provider name, not a model slug prefix. Use the full vendor/model ID, such as z-ai/glm-5.3-flashx, not openqiao/glm-5.3-flashx.

The plugin reads the live catalog at https://openqiao.com/api/v1/models. It keeps text-output models and filters image-only and video-only generation models out of the chat selector. A small fallback list is used only when the catalog is temporarily unavailable. Example models are not guaranteed to be available to every account; account permissions and API responses determine actual availability.

Models Outside the Catalog

The live catalog supports model selection and spelling suggestions; it is not an account permission allowlist. For account-specific, staged, or special-routing slugs, Hermes must support ProviderProfile.model_listing_authoritative to allow requests for unlisted slugs. Older Hermes versions may reject them before sending a request; update Hermes and the plugin first. Invalid or unauthorized slugs are still rejected by the 开桥 API.

Remote Servers and Headless Environments ​

OAuth uses a temporary loopback callback such as http://127.0.0.1:54321/callback. The port is not fixed.

  1. Start login in the remote terminal to obtain the current authorization URL and callback port:

    bash
    hermes auth add openqiao --no-browser

  2. Leave the remote login command waiting. Open another terminal on your local machine and forward the port actually shown for this login (54321 is only an example):

    bash
    ssh -N -L 54321:127.0.0.1:54321 user@remote-host

  3. Open the current authorization URL in your local browser, approve access, and check the result in the remote terminal.

Plugin version 0.1.1 and later waits up to 10 minutes. After a timeout, restart login and use the new URL and port; expired authorization codes cannot be reused. Do not expose the callback server to the public internet.

For hosted containers without SSH forwarding, the README describes authorizing with a temporary local HERMES_HOME and securely merging only credential_pool.openqiao. Transfer only that provider's credentials; never overwrite other remote provider credentials with an entire local auth.json. See the remote environment instructions.

Manage Authentication and Update ​

bash
# Inspect credentials, refresh explicitly, or log out
hermes auth list openqiao
hermes auth refresh openqiao
hermes auth logout openqiao

Update using your original installation method, then restart Hermes or the Gateway:

bash
hermes plugins install 开桥/hermes-plugin --force --enable
hermes gateway restart
bash
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade openqiao-hermes-plugin
hermes gateway restart

To stop using the plugin, run hermes auth logout openqiao, then hermes plugins disable openqiao. See the plugin README for complete removal instructions.

Option 2: API Key Custom Endpoint ​

You can still connect with an API Key without installing the OAuth plugin.

  1. Create a Subscription API Key or Pay-As-You-Go API Key. Refer to those pages for current plans, pricing, and quotas.

  2. Run hermes model and select Custom endpoint (enter URL manually).

  3. Enter the following values:

    SettingValue
    API Base URLhttps://openqiao.com/api/v1
    API KeyYour 开桥 API Key
    Model nameA full model ID, such as openai/gpt-5.4

  4. Run hermes and send a test message to confirm that the model responds.

Keep the Two Methods Separate

API Key custom endpoints use model.provider: custom; the OAuth plugin uses provider openqiao. When migrating from the old method, select the plugin provider again or set the default provider as shown above. Neither method adds a openqiao/ prefix to model IDs.

Troubleshooting ​

OAuth Plugin Issues ​

Unknown provider 'openqiao'

First confirm that Hermes meets the version requirement, then check that the plugin is installed and enabled:

bash
hermes plugins list
hermes plugins enable openqiao
hermes gateway restart

For PyPI installations, also check that the plugin is in the Python environment used by Hermes. Restart externally managed Gateways through their process manager.

OAuth Timeout or Authorization Failure

Run hermes auth add openqiao again and use the newly generated URL and port. Remote servers require forwarding as described in Remote authorization. Do not reuse authorization codes from expired login attempts.

If authentication fails after login, check hermes auth status openqiao and try hermes auth refresh openqiao. Sign in again if refreshing still fails.

Logged In, but Inference Reports a Missing Endpoint

Update the plugin and run hermes auth add openqiao again. The current plugin saves base_url=https://openqiao.com/api/v1 with credentials; early development versions did not save this field.

Model Rejected Because It Is Not in the Catalog

Check the full vendor/model slug first. For a valid unlisted model, update Hermes to a version supporting ProviderProfile.model_listing_authoritative, then update the plugin. Allowing an unlisted slug does not grant access; the 开桥 API response remains authoritative.

Common Issues ​

API Key Error or Authentication Failure

Problem: An invalid API Key or unauthorized error appears, such as 401 Unauthorized

Solution:

  1. Check the API Key format:

    • Subscription keys start with sk-ss-v1-
    • Pay-As-You-Go keys start with sk-ai-v1-
    • Make sure there are no extra spaces or line breaks

  2. Re-run hermes model: The easiest fix is to re-run the wizard and re-enter your API Key:

    bash
    hermes model

  3. Verify the key is still valid:

  4. Inspect the current config:

    bash
    hermes config
hermes config check
Requests Not Reaching 开桥

Problem: Requests seem to go to the default provider rather than 开桥

Solution:

  1. Re-run hermes model: For OAuth, select the plugin's 开桥 provider; for API Keys, select "Custom endpoint". Confirm the URL is https://openqiao.com/api/v1

  2. Check the current configuration:

    bash
    hermes config

    In the model section, verify that provider is openqiao for the OAuth plugin or custom for an API Key custom endpoint. The base_url should be https://openqiao.com/api/v1

  3. Double-check the base_url format:

    • Correct: https://openqiao.com/api/v1
    • Wrong: https://openqiao.com/v1, https://api.openqiao.com/v1
Connection Failure or Timeout

Problem: Hermes Agent cannot connect to 开桥

Solution:

  1. Test network connectivity:

    bash
    curl https://openqiao.com/api/v1/models

    If this returns a JSON model list, the connection is fine

  2. Check firewalls and proxies:

    • Make sure your firewall isn't blocking outbound HTTPS connections
    • Configure proxies with standard HTTP_PROXY / HTTPS_PROXY variables
    • If the proxy terminates TLS, configure its CA with SSL_CERT_FILE / REQUESTS_CA_BUNDLE; do not globally disable TLS verification

  3. DNS troubleshooting:

    bash
    nslookup openqiao.com
Unexpected Responses or Tool Calling Failures

Problem: The model produces unexpected output or tool calls fail

Solution:

  1. Confirm the model supports tool calling:

    • Hermes Agent relies on the model's native function calling capability
    • Some smaller models may not support tool calling, causing the agent to behave unpredictably
    • Recommended: GPT-5.x, Claude Sonnet/Opus, Gemini Pro, or other models with tool calling support

  2. Switch to a tool-calling-capable model: Run hermes model, select the 开桥 provider, and choose a model that supports tool calling

  3. Verify the model name:

    • Use the raw 开桥 model ID, 例如, openai/gpt-5.2
    • Do not add a openqiao/ prefix
    • Confirm the ID on the 开桥 Models page
429 Rate Limit Errors

Problem: Frequent 429 Too Many Requests errors

Solution:

  1. Check your plan quota: Subscription plans have request rate limits — consider upgrading or switching to Pay-As-You-Go

  2. Reduce concurrency: If you're running multiple model tasks in parallel, try lowering the concurrency

  3. Contact 开桥 support: If rate limiting persists, reach out to 开桥 technical support

Supported Models ​

开桥 offers a wide selection of models. Here are some popular picks for Hermes Agent:

ModelIDBest For
GPT-5.4openai/gpt-5.4High-performance general use, coding
Claude Opus 4.6anthropic/claude-opus-4.6Complex reasoning, coding
Claude Sonnet 4.6anthropic/claude-sonnet-4.6Balanced performance
Gemini 3 Progoogle/gemini-3.1-pro-previewMultimodal, long context
DeepSeek V3.2deepseek/deepseek-v3.2Cost-effective general use
Grok 4.2 Fastx-ai/grok-4.2-fastFast inference
Qwen3.6 Plusqwen/qwen3.6-plusGeneral reasoning
GLM 5.1z-ai/glm-5.1Chinese-language general use
Kimi 2.5moonshotai/kimi-k2.5Long context comprehension

For the complete list, visit the 开桥 Models page.

Contact Us ​

Email

Technical support: support@openqiao.com

Business cooperation: bd@openqiao.com

X / Twitter
@开桥AI
Discord
@开桥AI