Add devops/hermes-api-endpoint-setup

2026-07-10 16:11:28 +08:00
parent 24eee4dcf9
commit eb4bd039c2
1 changed files with 62 additions and 0 deletions
@@ -0,0 +1,62 @@
+---
+name: hermes-api-endpoint-setup
+description: "Configure Hermes Agent API endpoints: built-in API server and OneAPI-compatible proxy endpoints."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [hermes, api-server, oneapi, endpoint, configuration, proxy]
+    related_skills: [hermes-agent, openai-api-testing, llm-inference]
+---
+
+# Hermes API Endpoint Setup
+
+Two ways to expose Hermes Agent as an API: the built-in OpenAI-compatible API server, and connecting to OneAPI-compatible proxy endpoints.
+
+## Choosing an Approach
+
+| Need | Approach |
+|------|----------|
+| Expose Hermes as an API for other tools | **Built-in API Server** |
+| Route Hermes through a proxy/load balancer | **OneAPI Endpoint** |
+| Multiple model providers behind one endpoint | **OneAPI Endpoint** |
+| Custom port with external access | **Built-in API Server** |
+
+## Section 1: Built-in API Server
+
+Set up Hermes Agent's built-in OpenAI-compatible API server on a custom port with external access.
+
+**When to use:** Exposing Hermes Agent as an API server for other applications to consume.
+
+**Key config:**
+```bash
+hermes config set api_server.enabled true
+hermes config set api_server.port 8080
+hermes api-server start
+```
+
+**Critical pitfall:** Extra nesting in the API response format. The built-in server wraps responses in an extra layer. Clients expecting standard OpenAI format may need adjustment.
+
+**CRITICAL: Key strength.** The API server silently refuses to start if the key (in `platforms.api_server.extra.key` or `API_SERVER_KEY` env var) is < 16 chars or looks like a placeholder. Error only appears in `~/.hermes/logs/gateway.log`. Always use a strong 64-char hex key: `python3 -c "import secrets; print(secrets.token_hex(32))"`.
+
+**See:** `references/hermes-api-server-setup.md` for full configuration, SSL, and deployment guide.
+
+## Section 2: OneAPI Endpoint Configuration
+
+Connect Hermes Agent to a OneAPI-compatible proxy endpoint — set base_url, api_key, default model, auxiliary models, and delegation models.
+
+**When to use:** Routing Hermes through OneAPI, New API, or similar proxy platforms for load balancing, key management, or multi-provider aggregation.
+
+**Key config:**
+```bash
+hermes config set provider.custom.base_url "https://your-oneapi-instance.com/v1"
+hermes config set provider.custom.api_key "sk-*** hermes config set provider.custom.model "gpt-4o"
+```
+
+**Pitfalls:**
+- OneAPI model names may differ from upstream — use the names OneAPI defines
+- Rate limits are per-key in OneAPI — configure appropriate limits
+- Delegation models: set separately if using agent delegation
+
+**See:** `references/oneapi-custom-endpoint-setup.md` for full configuration and troubleshooting.