Obsidian Arc API网关实战:用OpenAI与Anthropic双兼容/v1接口接入Claude Code和Codex
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 小时 / 周 / 月限流
🚀 快速部署:一条命令跑起网关
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 端点有两个必须知道的约束:
- 无状态:
store必须省略或设为false,不支持previous_response_id/conversation恢复上下文,多轮历史由客户端每次完整携带 - 输出上限参数不同:这里读的是
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 双兼容」做成了开箱即用的能力:
docker run部署,开启api.enabled+api_access,在/keys建密钥- Claude Code 填实例根地址走
/v1/messages,Codex 填origin/v1走/v1/responses,或用密钥页一键导入 CC Switch - 用
/v1/models的id发起请求,出错查错误码表与请求日志
从此,一个网关、一把密钥、多套模型——开发工具接入 AI,不用再为不同协议维护多份地址和凭据。