Obsidian Arc API网关实战:用OpenAI与Anthropic双兼容/v1接口接入Claude Code和Codex

原创2026-11-10 22:15:011,329 阅读

Obsidian Arc API网关实战:用OpenAI与Anthropic双兼容/v1接口接入Claude Code和Codex

Obsidian Arc 是一款自托管的多用户 AI 对话服务与 API 网关,它把 OpenAI 兼容接口与 Anthropic Messages 兼容接口同时封装在 /v1 之下。只需一套接口地址和一把 API Key,就能让 Claude Code、Codex 等开发工具直接接入,还能统一做多服务商路由、用量记账与配额控制。本文带你从零完成部署、开网关、建密钥,再到两大客户端的实际接入配置。

🧭 先认识一下 Obsidian Arc

一句话概括:一个 Go 二进制 + 内嵌 Vue 前端 + SQLite/PostgreSQL,无需 Redis 和消息队列,docker run 即可跑起来。

与本文相关的核心能力集中在开发者网关(/v1):

  • 双协议兼容:既说"OpenAI 的话",也说"Anthropic 的话",工具调用格式自动互转
  • 多服务商聚合:上游可挂 OpenAI、DeepSeek、xAI、OpenRouter、Groq、Ollama、vLLM 及原生 Anthropic
  • 模型路由与别名:对外展示 api_name,内部映射到真实上游模型 ID
  • 用量账本:每次 API 调用与网页对话共用同一套额度体系,按 5 小时 / 周 / 月限流

更多功能细节见 README.md 与 快速配置指南。

🚀 快速部署:一条命令跑起网关

git clone https://gitcode.com/gh_mirrors/ob/ObsidianArc
cd ObsidianArc
docker build -t obsidian-arc .
docker run -d -p 8080:8080 -v arc-data:/data \
  -e OBSIDIAN_SECRET_KEY=$(openssl rand -hex 32) obsidian-arc

默认监听 :8080,首个注册的用户自动成为管理员。

网关对外生效还需要三个开关:

步骤 位置 操作
1️⃣ 系统设置 开启 api.enabled(全站 API 总开关)
2️⃣ 用户组 为目标组开启 api_access
3️⃣ /keys 页面 用调用方账号创建 API Key,明文只在创建时出现一次,务必保存

在此之前,管理员还应先到 /admin/providers 配置上游服务商、到 /admin/models 添加模型(见服务商与模型)。密钥可以绑定具体模型范围,不绑定则跟随账号权限。

📡 /v1 端点速览:一次看清全部接口

方法与路径 用途 典型客户端
POST /v1/chat/completions OpenAI 对话兼容 OpenAI SDK、各类脚本
POST /v1/messages Anthropic Messages 兼容 Claude Code
POST /v1/messages/count_tokens 输入 Token 估算 Claude Code(上下文预算)
POST /v1/responses OpenAI Responses 兼容 Codex
POST /v1/images/generations 图像生成 —
GET /v1/models、GET /v1/models/{id} 模型列表与详情 所有客户端

认证推荐 Authorization: Bearer YOUR_API_KEY,也接受 x-api-key 头。完整端点与错误码清单见 接入与鉴权。

🤖 接入 Claude Code:Anthropic Messages 双兼容

Obsidian Arc 专门实现了 Anthropic 风格的消息、工具与流式事件结构,并提供了 count_tokens 端点——这正是 Claude Code 这类 Agent 客户端的依赖项(实现见 messages.go 与路由注册 compat.go)。

关键:基础地址怎么填?

Claude Code 会自行拼接 /v1/messages,所以基础地址要填实例根地址,而不是带 /v1 的地址:

配置项 填写值
基础地址(如 ANTHROPIC_BASE_URL) https://ai.example.com
API Key 你的 Obsidian Arc 密钥
模型名 /v1/models 返回的 id

如果客户端要求填完整端点,则填 https://ai.example.com/v1/messages。

💡 省力技巧:在 /keys 页面创建密钥后,可点击「一键导入 CC Switch」,选择目标客户端 Claude Code,会自动生成导入链接(前端实现见 cc-switch.ts 与 KeysPanel.vue),无需手工复制地址。

几个容易踩的坑:

  • max_tokens 调用时请明确提供,Claude Code 每次请求都会带上
  • 工具结果(tool_result)只支持文本,图片请放在用户消息里
  • 缓存断点 cache_control(含 ttl: "5m" / "1h")会被保留转发,是否命中由上游决定
  • 协议细节详见 Anthropic Messages 文档

⚡ 接入 Codex:OpenAI Responses 接口

Codex 走的是 OpenAI Responses 协议,Obsidian Arc 通过 /v1/responses 提供该格式的输入、输出与流式事件(实现见 responses.go)。

配置要点:

配置项 填写值
基础地址(base_url) https://ai.example.com/v1(客户端会自行拼接 /responses)
API Key 你的 Obsidian Arc 密钥
模型名 /v1/models 返回的 id

Responses 端点有两个必须知道的约束:

  1. 无状态:store 必须省略或设为 false,不支持 previous_response_id / conversation 恢复上下文,多轮历史由客户端每次完整携带
  2. 输出上限参数不同:这里读的是 max_output_tokens,不是 Chat Completions 的 max_tokens

Codex 客户端同样支持从密钥页一键导入(选择 Codex 即可)。完整参数与返回结构说明见 Responses 文档。

顺带一提:如果你的工具走标准 OpenAI Chat 协议(如各类 SDK 脚本),用 POST /v1/chat/completions 即可,基础地址填 https://ai.example.com/v1,参数见 Chat Completions 文档。

✅ 验证连通:两条 curl 命令自测

先拿模型列表,确认密钥与权限都正常:

curl https://ai.example.com/v1/models \
  -H "Authorization: Bearer $OBSIDIAN_API_KEY"

返回的 id 才是调用时真正要用的名字(display_name 仅用于展示,见模型列表文档)。再发一条流式对话:

curl -N https://ai.example.com/v1/chat/completions \
  -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model","stream":true,"messages":[{"role":"user","content":"你好"}]}'

客户端连不上时的排查顺序:① 确认请求真的落到了上表端点(别把基础地址和完整路径重复拼接)→ ② 检查模型权限与 api_name 别名 → ③ 到后台请求日志查错误码。

🛠️ 常见错误码速查表

HTTP 状态 错误码 含义与对策
404 api_disabled 全站 API 未开启,管理员先开 api.enabled
401 invalid_api_key 密钥缺失/无效,或账号、用户组无调用权限
401 api_key_paused 密钥已暂停,到 /keys 恢复
403 account_banned 账号被封禁,message 中带封禁理由
404 model_not_found 模型名解析不到,检查 id 或 api_name
403 model_not_permitted 模型不在密钥绑定范围内
429 见响应 触达额度、频率或并发限制

注意:流式请求开始后,错误可能通过流内事件返回,客户端不能只检查最初的 HTTP 状态。

📊 配额、用量与安全边界

  • 共用账本:API 调用与网页对话共用账号额度,写入追加式用量账本,5 小时 / 周 / 月多窗口限流,数据库行锁防止并发透支
  • 密钥最小权限:密钥可绑定指定模型;绑定范围的密钥不会获得范围外的访问权
  • 模型路由:借助 api_name 与单跳路由,可以给 Claude Code / Codex 一个稳定的对外模型名,后台随时切换实际执行模型而无需改客户端
  • 上游密钥加密:服务商 API Key 经实例密钥派生加密后入库,管理接口不回传明文
  • 计费口径:内部账本将输出与推理 Token 分开记录;上游无统计时才用本地估算并在账本标记

🎯 小结

Obsidian Arc 的 /v1 网关把「OpenAI 与 Anthropic 双兼容」做成了开箱即用的能力:

  1. docker run 部署,开启 api.enabled + api_access,在 /keys 建密钥
  2. Claude Code 填实例根地址走 /v1/messages,Codex 填 origin/v1 走 /v1/responses,或用密钥页一键导入 CC Switch
  3. 用 /v1/models 的 id 发起请求,出错查错误码表与请求日志

从此,一个网关、一把密钥、多套模型——开发工具接入 AI,不用再为不同协议维护多份地址和凭据。

延伸阅读:API 总览 · 首次配置 · 部署与升级 · 服务商与模型管理

登录后查看全文
ObsidianArc