Agent clients / OpenAI Compatible

AI Agent 接入中心：先确认协议，再选择对应客户端配置。

This page is for Hermes Agent / OpenClaw / Codex CLI / Claude Code / Cline / Roo Code users. The practical goal: know which clients can directly use an OpenAI-compatible endpoint, which ones have protocol boundaries, what to verify first, and what to check when something fails.

Unified baseline:MonkeyAI customer endpoint is https://monkeytheme.com/v1. If the client supports OpenAI-compatible / custom OpenAI, it can usually connect directly. Claude Code native mode is the key exception: it leans toward the Anthropic Messages protocol and should not be presented as fully equivalent to OpenAI-compatible.
Test the API firstGenerate config
Recommended onboarding flow

推荐接入顺序

  1. 先用 Agent API Tester 验证 Key、Base URL、模型名。
  2. 再用 配置生成器 复制对应客户端的配置示例。
  3. 最后回到你的目标客户端里发一条最短真实请求，确认它不是只在浏览器里通。
避免在未确认接口可用的情况下修改大量配置。正确的顺序是：先确认 API 可用，再接入目标客户端。
Direct fit

Hermes Agent / OpenClaw

这类 Agent 用户是 MonkeyAI 最核心的目标客户之一。它们通常都能通过自定义 provider 或 OpenAI-compatible 方式接入，但真正影响成功率的，是是否已经完成直连 API 验证。

  • 先确认 /v1/models 能列出模型。
  • 再确认 /v1/chat/completions 用真实模型名能回字。
  • 再把 Base URL、Key 和模型名写入 Hermes / OpenClaw 配置。
  • 如果是 Hermes 网关在跑，切模型 / provider 前先验证 API，再重启 gateway。
curl https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer sk-你的Key"
Needs version awareness

Codex CLI

Codex CLI 更适合配置文件 / 环境变量方式管理。它的问题通常不在请求发送本身，而在于 不同版本的配置入口、provider 支持与环境变量命名可能不同。建议按以下顺序处理：

  1. 先用 API Tester 验证 Key、Base URL 与模型名。
  2. 确认你当前 Codex CLI 版本支持自定义 OpenAI / Base URL 的接法。
  3. 再用配置生成器复制示例，落到你当前版本需要的位置。

如果需要为客户提供配置说明，建议同时准备环境变量方案和配置文件方案，降低版本差异带来的支持成本。

Protocol caveat

Claude Code

重点：Claude Code 原生模式更偏 Anthropic Messages 协议。它不是“换个 Base URL 就一定能当 OpenAI-compatible 客户端用”的那种工具。

你想用 Claude 模型
推荐走 Cline / Roo Code / Cherry Studio 这类 OpenAI-compatible 客户端接 MonkeyAI。
你坚持用 Claude Code 原生
那就要先确认当前入口是否支持它要的 Anthropic 协议，而不是把 Key 问题和协议问题混在一起。

所以，对外文档口径要专业一点：Claude Code 原生协议有边界；如果只是想用 Claude 模型，优先推荐可直接走 OpenAI-compatible 的客户端。

Best for fast onboarding

Cline / Roo Code / Cherry Studio

这类客户端对新客户最为友好，通常支持直接填写 Base URL、API Key 和模型名，无需额外协议配置。

  • Base URL 填 https://monkeytheme.com/v1
  • API Key 填后台生成的 sk-...
  • 模型名应使用后台真实可见的完整名称
  • 先发一条最短消息验证，成功后再执行复杂工作流
Troubleshooting

常见问题清单

  1. 401 unauthorized：Key 不完整、复制错账户、前后有空格。
  2. /v1/v1：你手动写了一次，客户端又自动补了一次。
  3. model not found：模型名不是价目表里真实在售名。
  4. Claude Code 不通：优先怀疑协议不匹配，不应优先判断为 Key 错误。
  5. 只在网页测试里能通：还要回到目标客户端里做一次真实消息验证。
  6. Hermes 改完没生效：需要新开 session 或重启 gateway，而不是期待当前会话自动热更新。
这页是 Agent 用户的入口总览。真正落配置时，建议配合“Agent API Tester”和“配置生成器”一起用。