你可能已经在本地把某个开源模型跑起来了，Ollama 或 vLLM 的接口都能通，但一接到 Claude Agent SDK 上就各种不通：要么连不上，要么工具调用直接哑掉，要么长任务跑到一半上下文炸了。这篇不讲该不该自建，只讲怎么把这个 SDK 接到你自己的推理服务上，以及接完之后按什么顺序验一遍才算真的能用。
你可能已经在本地把某个开源模型跑起来了，Ollama 或 vLLM 的接口都能通，但一接到 Claude Agent SDK 上就各种不通：要么连不上，要么工具调用直接哑掉，要么长任务跑到一半上下文炸了。这篇不讲该不该自建，只讲怎么把这个 SDK 接到你自己的推理服务上，以及接完之后按什么顺序验一遍才算真的能用。
先摆正一个预期：Agent SDK 本身不关心你的模型跑在哪，它只关心对面那个 HTTP 端点回的东西对不对。所以绝大多数「接不上」的问题，根子在协议对不上或者字段丢在中间层，而不在模型本身。下面按排查顺序走。
先想清楚中间隔了哪一层
Agent SDK 走的是 Anthropic 风格的 Messages 接口，而本地推理框架多数只原生提供 OpenAI 兼容接口。两边对不上时，中间要么加一层转换网关，要么直接选本身就带 Anthropic 兼容端点的推理服务。判断顺序是先确认你的推理框架支持哪种协议，再决定是换框架、加转换层，还是只在 SDK 侧改 base_url 和鉴权头。
- 先查你的推理框架文档里有没有 Anthropic 兼容端点，有的话最省事，直接改 base_url；
- 没有的话看它是否有社区维护的转换插件，能用就别自己写；
- 两种情况都不满足，才考虑在前端加一层自建网关，把 Messages 请求翻译成 OpenAI 格式再转发；
- 如果只有单轮问答、不用工具调用和流式，那根本不必上 Agent SDK，直接用普通客户端更省事。
配置怎么落：端点和密钥两件事
配置层面其实只有两件事：base_url 指向哪里，鉴权头怎么写。但这两件事最容易配错，而且错的方式很隐蔽——不会直接报错，而是表现成「一部分请求通、一部分超时」。所以改完先别急着跑 Agent 流程，用一条最小请求确认返回结构对得上，再去接工具。
- base_url
- 直接指向你本地服务的地址，不要把官方域名和本地地址混着配
- 鉴权头
- 按你本地服务实际要求来；本地常常不校验 key，但 SDK 通常要求一个非空值，随便填个占位串，不要留空
- 模型名
- 填你本地服务里真实注册的那个标识，填官方模型别名一般会直接返回未找到模型
- 代理开关
- 如果你本机原本配了系统级代理，记得把本地地址加进不走代理的名单，否则请求会被绕出去
- 最小连通验证只发一条不含工具、不含历史的普通对话请求，确认能拿到结构完整的回复。这一步能过，说明协议和鉴权没问题。
- 流式验证再开流式模式发一次同样的请求，看事件是否能正常分块返回。流式挂了说明转换层没做事件透传。
- 错误码验证故意把一个模型名改成不存在的，看返回的错误结构是否规范。错误结构不规范会让 SDK 后续重试逻辑乱掉。
真正卡人的是上下文和工具调用
到这一步你大概能连上了，但 Agent 一跑长任务就出问题。原因是 Agent 的多轮循环会不断把历史堆回去，而本地模型的可用上下文往往比你预期短。跑长任务前先估算每轮增长的 token 量，必要时在 SDK 侧做历史裁剪，比如只保留最近若干轮加一条摘要。
工具调用是最大的分水岭。参数格式、并行调用、调用失败后的重试行为，各家本地模型差异很大。先拿一个只有单个工具的最小例子验证，通了再往上加。模型自身能力不够时会表现为「工具参数编造」或「反复调同一个工具」，这通常不是 SDK 的问题，而是模型与提示词的问题，先换提示词再考虑换模型。
| 现象 | 优先怀疑 | 下一步动作 |
|---|---|---|
| 请求直接超时 | 地址或代理配置 | 检查 base_url 和代理绕过名单 |
| 回复结构缺字段 | 转换层字段丢失 | 对照 /stacks/frameworks 的支持范围 |
| 工具调用返回空 | 模型不支持或提示词太弱 | 换单工具最小例子单独测 |
| 长任务中途断 | 上下文超长或超时设置 | 做历史裁剪，调大超时阈值 |
| 并发一高就排队 | 本地服务并发上限 | 按 /models/deploy 的算例重设并发数 |
跑通之后按这个顺序验收
很多人的验收方式就是「随便问一句能回就算好了」，这在本地模型上完全不成立。要按从简单到复杂的顺序逐步加压，每一步都记录延迟和失败率，差值大就说明转换层有问题。失败率高的地方优先怀疑上下文长度和超时设置，而不是模型质量。
- 单轮无工具对话确认基础链路和返回结构正常，这是所有后续步骤的基线。
- 单工具调用只挂一个工具，验证参数能被正确解析并且调用结果能被模型消化。
- 两到三个工具的串行调用验证多轮工具链是否稳定，观察每轮之间上下文的增长速度。
- 长任务多轮循环跑一个需要多轮往复的任务，看上下文是否稳定、是否出现中途截断。
延迟对比上，先用 /tools/speed-test 量出你本地服务的基线延迟，再对比 SDK 链路的整体延迟，两者差值大就说明中间层拖了后腿。显存与并发怎么配才不炸，去 /models/deploy 按你的模型和量化档位算一遍再定并发数，别照搬官方服务的并发习惯。
下一步把你本地推理框架的协议支持情况、常用中转与自托管方案放在一起对照，能省掉大量试错。先到 /stacks/frameworks 确认你的框架在这份清单里的位置，再决定改哪儿。→常见问题
本地模型没有 Anthropic 风格的接口，还能用这个 SDK 吗？
可以，但要在中间加一层协议转换，把 Anthropic 风格的请求翻译成你本地服务的 OpenAI 兼容接口。已有现成的转换网关可挑，也可以自己写一层薄代理。要注意工具调用和流式这两块最容易翻译不全，先拿最小例子验证再上业务。
接上之后工具调用一直失败，是 SDK 的问题吗？
多数不是。先看本地模型本身有没有稳定的 function calling 能力，很多小参数模型这块很弱。再看提示词里工具描述是否够明确、参数 schema 是否过于复杂。排查顺序是：换一个最简单的单工具例子试，能通就说明是复杂度和模型能力问题。
本地服务要不要开鉴权？SDK 那边怎么配？
内网自用可以不开，但 SDK 一般要求提供一个非空的 key 值，随便填个占位串就行。如果服务暴露在局域网之外，务必加上鉴权和访问控制，否则等于把推理资源对外开放。配置完先用一条最小请求确认能返回正常结构。
