Dify 配置 Anthropic 兼容 API：先分协议，再填模型、Key 和 Base URL
简答：Dify 可以接入 Anthropic 兼容 API，但不能把所有接口都当成同一种格式。先确认网关提供的是原生 Anthropic Messages、OpenAI 兼容 Chat Completions，还是通过 Dify 的 Claude Proxy 插件接入；然后按协议选择插件，模型 ID 使用网关文档或模型列表返回的原始值，Base URL 不要凭经验统一追加 /v1。
定义：Anthropic 兼容 API 是指请求格式、认证头和响应结构能够按照 Anthropic Messages API 工作的接口；如果接口实际提供的是 /chat/completions，则它属于 OpenAI 兼容 API，应该使用不同的 Dify 模型提供商。
先看这张表：你的接口到底该选哪种 Dify 配置
本文只解决一个问题：在 Dify 中配置 Anthropic 兼容 API。本站是第三方 AI API 接入指南站，不是 Dify、Anthropic 或任何接口服务的官方站点。配置前先向接口提供方确认它公开的是哪一种协议；同一个 Claude 模型名称，并不代表所有网关都使用同一套请求路径。
| 接口类型 | Dify 入口 | 认证方式 | Base URL 判断 | 适合的能力 |
|---|---|---|---|---|
| 原生 Anthropic Messages | 官方 Anthropic 插件，或支持原生 Messages 的 Claude Proxy 插件 | 通常是 x-api-key，并需要 anthropic-version | 按网关要求填写；不要默认追加 /v1 | Messages、原生工具调用、原生图像内容；官方插件还提供 Prompt Caching 选项 |
| OpenAI 兼容 Chat Completions | Dify 的 OpenAI-API-compatible 插件 | 通常是 Authorization: Bearer | 通常填服务商要求的 API 根地址；是否包含 /v1 必须以该网关文档或实测路径为准 | 对话、流式、部分工具调用和 Vision，具体取决于网关实现 |
| Claude Proxy 插件 | Dify Marketplace 中的 Claude Proxy | 由代理插件转发到原生 Messages 兼容接口 | 填写代理的 API Base URL，不要把 OpenAI 的 /chat/completions 地址填进来 | 原生 Messages、流式、非流式和工具调用，前提是代理确实实现这些能力 |
Dify Marketplace 的 Anthropic 插件说明要求配置 API Key 和 API URL，并提供 Prompt Caching 相关选项；OpenAI-API-compatible 插件说明则明确采用 OpenAI API 标准，并要求填写类型、模型名、Key 和 URL。Claude Proxy 的 Marketplace 页面说明它面向实现原生 Anthropic Messages API 的自定义代理地址。
第一步：用最小请求判断网关协议
不要先在 Dify 里反复保存配置。先用同一组 Key 和模型 ID 发一个最小请求，可以把“协议不匹配”“Key 无效”“模型名错误”和“Dify 容器无法联网”分开。
测试原生 Anthropic Messages
把 BASE 替换为网关要求的地址，把 <MODEL_ID> 替换为官方模型列表或网关 /models 返回的模型 ID。模型 ID 不是展示名，也不要直接照抄其他教程中的旧 ID。
curl -sS -o anthropic-response.json -w "%{http_code}\n" "$BASE/v1/messages" -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"<MODEL_ID>","max_tokens":64,"messages":[{"role":"user","content":"只回复 OK"}]}'
原生 Messages 请求至少要有 x-api-key、anthropic-version、content-type、model、max_tokens 和 messages。Anthropic 的图像示例也使用 x-api-key、anthropic-version 和 max_tokens，可参考 Anthropic 视觉能力文档。
测试 OpenAI 兼容 Chat Completions
如果接口方明确提供 OpenAI 兼容端点，测试地址应按其文档拼接。下面只展示常见形式，BASE 是否已经包含 /v1 不应自行猜测。
curl -sS -o openai-response.json -w "%{http_code}\n" "$BASE/chat/completions" -H "Authorization: Bearer $API_KEY" -H "content-type: application/json" -d '{"model":"<MODEL_ID>","messages":[{"role":"user","content":"只回复 OK"}],"max_tokens":64,"stream":false}'
如果两个请求都返回 200，说明网关可能同时支持两种协议。此时不要继续猜 URL，而应按功能选择：需要 Anthropic 原生字段或 Prompt Caching 时走 Messages；需要 Dify 的 OpenAI 兼容配置、手动 Vision 或某些 Chat Completions 工具调用时，走 OpenAI 兼容接口，并以实际响应能力为准。
第二步：在 Dify 中按协议填写字段
方案 A：官方 Anthropic 插件
- 在 Dify 的插件或模型提供商入口安装官方 Anthropic 插件。
- 新增凭据，填写 API Key；如果界面提供 API URL，则填接口方明确给出的 Anthropic Messages 根地址。
- 添加模型时，Model Name 填网关要求的原始模型 ID；不要填中文显示名，也不要擅自加供应商前缀。
- 先关闭 Vision、工具调用和 Prompt Caching 等附加能力，只测试普通文本；普通请求成功后，再逐项打开并测试。
- 如果接口并非 Anthropic 原生协议，而只是 OpenAI 兼容，不要使用这个入口。
官方插件页面显示，Anthropic 插件支持 Claude 家族模型配置，并提供 Prompt Caching 选项。缓存块数量、图片、PDF、系统提示和工具定义等行为属于插件与上游 API 的组合能力，不能因为普通文本请求成功，就推断所有缓存或多模态能力都可用。
方案 B：OpenAI-API-compatible 插件
- 安装 Dify 的 OpenAI-API-compatible 模型插件。
- Type 选择 LLM 或 Chat 模型类型，Model Name 填接口实际接受的
<MODEL_ID>。 - API Key 填网关 Key，API Base URL 按接口文档填写。若文档给的是
https://example.invalid/v1，先用 curl 观察插件实际拼出的路径，避免重复添加版本路径。 - Completion mode 选择接口实际支持的对话模式。不要把只支持 Chat Completions 的地址当成 Responses 或 Messages 地址。
- 先关闭 Vision、Function Calling 和 Streaming，完成普通文本测试后再逐项启用。
- 上下文长度和最大输出不要沿用其他平台的默认数字，应填网关允许值或模型官方文档给出的值；无法核实就先保守填写，并以实际错误响应为准。
Dify Marketplace 的插件说明明确列出模型名、API Key、URL、补全、上下文、Token 限制、流式和 Vision 等配置项，但它不会替你确认某个外部网关的模型 ID、路径或能力。因此这些字段必须以你的接口提供方文档或返回结果为准。
方案 C：Claude Proxy 插件
- 安装 Dify Marketplace 中的 Claude Proxy 插件。
- 在模型提供商中打开 Claude Proxy，新增模型。
- 填写 Model Name、API Key、API Base URL 和 Max Tokens。
- 确认代理实现的是原生 Anthropic Messages API，而不是只有 OpenAI
/chat/completions。 - 先测试普通文本，再测试流式和工具调用；若代理只实现部分字段，Dify 中对应能力应保持关闭。
Claude Proxy 的 Marketplace 页面把它定义为连接到“实现原生 Anthropic Messages API 的自定义代理端点”的模型提供商，并列出模型名、Key、Base URL 和最大输出字段。它的能力描述不能替代你所使用代理的接口文档，代理支持范围仍需单独核实。
第三步：模型 ID、Base URL 和能力开关怎么核对
| 配置项 | 正确做法 | 常见错误 |
|---|---|---|
| 模型 ID | 从官方模型列表、网关文档或网关 /v1/models 返回值复制 | 把展示名、别名、旧教程中的 ID 或自定义标签直接填入 |
| Base URL | 先确认插件会自动拼接什么路径，再决定是否包含 /v1 | 看到“兼容 API”就一律追加 /v1，导致 404 或重复路径 |
| 认证头 | Messages 通常核对 x-api-key 和 anthropic-version；OpenAI 兼容通常核对 Bearer | 用 Bearer 测原生 Messages，或用 x-api-key 测只支持 OpenAI 兼容的端点 |
| Vision | 先确认模型、插件和网关都支持图像内容，再在 Dify 打开 | 只凭模型名称判断识图可用，或只打开 Dify 开关却没有验证请求格式 |
| 工具调用 | 先用一个简单工具测试参数结构、调用结果回传和多轮响应 | 普通文本成功就认为 Agent 工具调用一定可用 |
| Streaming | 普通非流式请求成功后再启用，并观察 SSE 是否完整结束 | 一开始就开流式，无法判断是网络、代理还是协议问题 |
Anthropic 的视觉文档说明，图像可以通过 URL 或 Base64 放入 Messages 请求，支持的格式包括 JPEG、PNG、GIF 和 WebP；但 Dify 的 Vision 开关、代理转换层和上游模型都必须同时支持，才有实际效果。若你只需要文本对话，建议先关闭 Vision，减少排查变量。
自部署 Dify：先在容器里测试，不要只在宿主机测试
自部署环境最容易出现“宿主机 curl 成功，但 Dify 超时”。原因通常不是 Key，而是插件运行容器的网络视角不同。应进入实际发起请求的 Dify API 或插件守护进程容器执行测试；容器中的 localhost 指向容器自身，不是宿主机。
- 先在宿主机执行最小请求，记录状态码和响应体。
- 再使用
docker exec -it <container_name> sh或容器实际提供的 shell 进入相关容器。 - 在容器内重复同一个请求，比较 DNS、路由、证书和响应状态。
- 如果接口服务运行在宿主机，Linux Docker 环境通常需要使用宿主机可达地址；在 Docker Desktop 环境中，
host.docker.internal是否可用取决于运行环境，不能把它当作所有部署方式的固定答案。 - 如果容器内连不上，先处理网络、代理、DNS、防火墙和证书，再回到 Dify 字段排查。
不要把真实 Key 写进镜像、提交到仓库或粘贴到公开日志。测试时把响应体写入临时文件，并只输出状态码；如果响应中可能包含请求信息，分享日志前应脱敏。
401、403、404、429 和超时：按状态码定位
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 401 | Key 是否过期、撤销、复制错误；认证头是否与协议匹配 | Messages 重新核对 x-api-key；OpenAI 兼容重新核对 Bearer；不要把 Key 放进 URL |
| 403 | 组织、工作区或模型权限 | 确认该 Key 是否有目标模型和接口权限；Dify 保存成功不等于上游模型授权成功 |
| 404 | Base URL、路径拼接和模型 ID | 对照 curl 的最终请求地址，排除重复 /v1、误用 /messages 或 /chat/completions |
| 429 | 速率限制、月度额度、并发和重试策略 | 读取响应头中的 Retry-After；降低并发，采用退避重试；如果是额度上限，等待不会自动解决 |
| 超时 | 容器网络、代理转发、请求过大、长输出和流式设置 | 先发短文本、低 max_tokens 的非流式请求，再逐步增加上下文和启用流式 |
Anthropic 的错误文档将 401 归为认证错误、403 归为权限错误、404 归为资源或路径不存在、429 归为速率或额度限制，并说明 429 不一定都会带 retry-after；长请求还可能遇到 504，流式响应则可能在已经返回 200 后于中途产生错误。可参考 Anthropic API 错误文档，不要只根据 Dify 界面显示的“连接失败”判断原因。
如果需要重试，先保存状态码、响应体和 request ID，不要盲目快速循环。对于 429 或 5xx，按响应头给出的等待时间处理；没有等待时间时采用逐步增加的退避间隔，并设置最大重试次数。对于 401、403、404，重试通常不能修复配置错误。
Agent、识图和 Prompt Caching 为什么可能单独失败
普通对话成功，只能证明一条最小文本链路可用，不能证明 Dify Agent、Vision 或 Prompt Caching 也可用。
- Agent 工具调用：需要 Dify 的 Agent 策略、模型提供商、网关转换层和上游模型共同支持工具定义与工具结果回传。先测试一个参数少的工具，确认模型返回的是结构化调用，而不是把工具名当普通文本输出。
- 识图：需要 Dify 传出图像内容块，网关保留或正确转换图像字段，上游模型具备视觉能力。Anthropic 文档建议图像清晰、方向正确；低质量或过小图像可能导致错误，具体可参考 视觉能力文档。
- Prompt Caching：只有当所选入口、代理和上游接口都支持对应缓存字段时才有意义。官方 Anthropic 插件提供缓存相关选项，但通过 OpenAI 兼容接口时不能据此推断缓存字段会被保留。
- 流式：流式是传输方式，不是模型能力开关。普通请求成功而流式中断时，应检查 SSE 转发、反向代理缓冲、超时和容器日志。
结论：Dify 配置 Anthropic 兼容 API 的最短路径
- 向接口提供方确认协议：Messages 还是 OpenAI Chat Completions。
- 用最小 curl 请求验证 Key、模型 ID 和最终路径。
- 原生 Messages 选 Anthropic 或 Claude Proxy；OpenAI 兼容选 OpenAI-API-compatible。
- Base URL 只按插件拼接规则和网关文档填写，不要机械追加
/v1。 - 先关闭 Vision、工具调用、缓存和流式，只验证普通文本。
- 普通文本成功后一次只打开一个能力，并保留状态码、响应体和 request ID。
- 自部署用户必须在实际 Dify 容器内重复测试，特别检查
localhost与宿主机地址的区别。
如果你无法确认网关协议、模型 ID 或 Base URL，最稳妥的做法不是继续试错，而是索取该接口的请求示例、模型列表返回和路径说明。本文未展开具体服务商的价格、可用性、限速数值和实际测速，这些信息必须以对应服务商的最新官方资料为准。
常见问题
Dify 配置 Anthropic 兼容 API 时，Base URL 一定要加 /v1 吗？
不一定。是否包含 /v1 取决于所选插件的路径拼接规则和网关文档。原生 Messages 与 OpenAI 兼容接口的路径不同，建议先用 curl 打印最终请求地址并排除重复路径。
Anthropic 原生接口和 OpenAI 兼容接口的 Key 写法一样吗？
通常不一样。原生 Anthropic Messages 通常使用 x-api-key，并带 anthropic-version；OpenAI 兼容接口通常使用 Authorization: Bearer。最终应以接口文档和最小请求结果为准。
Dify 里普通文本能用，但 Vision 或 Agent 不能用，是什么原因？
普通文本成功只证明基础请求可用。Vision 还需要图像字段、网关转换层和模型能力同时支持；Agent 还需要工具定义和工具结果回传链路完整。请先逐项开启能力，不要一次全部打开。
模型 ID 可以直接填 Claude 的展示名称吗？
不建议。模型 ID 必须使用官方模型列表、网关文档或模型列表接口返回的原始值。本文统一使用 <MODEL_ID> 占位，请从官方模型列表复制后再填写。
Dify 自部署时为什么宿主机 curl 成功，容器里却超时？
因为容器中的 localhost 指向容器自身，和宿主机不是同一个网络视角。应进入实际发请求的 Dify 容器重复测试，并检查容器 DNS、代理、证书和宿主机可达地址。
429 错误等待 Retry-After 就一定能恢复吗？
不一定。429 可能来自速率限制，也可能来自额度或支出上限。速率限制可以按 Retry-After 退避重试；额度上限则需要恢复额度或调整账户配置，不能只靠重试解决。
参考资料
- Dify Marketplace：Anthropic 插件（marketplace.dify.ai）
- Dify Marketplace：OpenAI-API-compatible 插件（marketplace.dify.ai）
- Dify Marketplace：Claude Proxy 插件（marketplace.dify.ai）