OpenClaw 接入 Synthetic 提供商:Anthropic 兼容 API、模型发现机制与配置详解【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文基于 OpenClaw 仓库中docs/providers/synthetic.md官方文档,讲解如何通过官方openclaw/synthetic-provider插件接入 Synthetic 的 Anthropic 兼容端点:包括插件安装、SYNTHETIC_API_KEY认证、onboarding 流程、完整配置示例,以及结合插件源码剖析其静态种子目录 实时模型发现的目录刷新机制。读完你能够独立在 OpenClaw 中配置 Synthetic 提供商,并理解模型引用格式synthetic/modelId、base URL 覆盖规则与模型发现过滤逻辑。提供商概览Synthetic 对外暴露 Anthropic 兼容端点,OpenClaw 通过官方openclaw/synthetic-provider插件接入,推理流量走 Anthropic Messages API。核心属性如下:属性值Provider IDsynthetic认证方式环境变量SYNTHETIC_API_KEYAPI 协议Anthropic MessagesBase URLhttps://api.synthetic.new/anthropic在插件清单 openclaw.plugin.json 中可以看到这一设计的具体声明:providers: [synthetic]与setup.providers[].envVars: [SYNTHETIC_API_KEY]声明了认证所需的环境变量;enabledByDefault: true且activation.onStartup: false,即插件默认启用但不在启动时激活,随配置生效;modelCatalog.discovery.synthetic: refreshable声明该提供商的模型目录支持实时刷新,对应下文模型发现一节;providerAuthChoices中定义了 onboarding 认证选项choiceId: synthetic-api-key、CLI 参数--synthetic-api-key key,分组提示为 Anthropic-compatible (multi-model),即 Synthetic 是Anthropic 兼容、多模型类的接入方式。插件包 package.json 显示当前版本为2026.9.4,要求宿主minHostVersion: 2026.7.2。快速开始官方文档给出的四步接入流程如下,每步都附带可直接执行的命令。1. 安装插件openclaw plugins install openclaw/synthetic-provider安装会自动作用于运行中的 Gateway;若 Gateway 未在运行,则在下一次启动时生效。2. 获取 API Key从你的 Synthetic 账户获取SYNTHETIC_API_KEY,或者在 onboarding 流程中按提示输入。3. 运行 onboardingopenclaw onboard --auth-choice synthetic-api-key--auth-choice参数值与插件清单中声明的choiceId: synthetic-api-key一一对应。onboarding 期间,预设应用器会把认证、base URL、种子模型目录一并写入配置,源码见 onboard.ts:const syntheticPreset { primaryModelRef: SYNTHETIC_DEFAULT_MODEL_REF, resolveParams: () ({ providerId: synthetic, api: anthropic-messages, baseUrl: SYNTHETIC_BASE_URL, catalogModels: () SYNTHETIC_MODEL_CATALOG.map(buildSyntheticModelDefinition), aliases: [{ modelRef: SYNTHETIC_DEFAULT_MODEL_REF, alias: MiniMax M3 }], }), } satisfies Parameterstypeof createProviderConnectionPresetAppliers[][0];可以看出 onboarding 通过 plugin-sdk 的createProviderConnectionPresetAppliers/createModelCatalogPresetAppliers完成三件事:写入anthropic-messages协议与默认 base URL、把种子模型目录展开为模型定义、并为默认模型建立MiniMax M3别名。4. 验证默认模型onboarding 会将默认模型设为synthetic/hf:MiniMaxAI/MiniMax-M3,可用下面的命令确认其已注册:openclaw models list --provider syntheticBase URL 使用要点:不要手动加 /v1官方文档中有一条重要的警告值得强调:OpenClaw 的 Anthropic 客户端会自动在 base URL 后追加/v1,因此应使用https://api.synthetic.new/anthropic(而不是/anthropic/v1)。如果 Synthetic 变更了 base URL,可通过models.providers.synthetic.baseUrl覆盖。这一约束在源码中的体现是 models.ts 导出的常量:export const SYNTHETIC_BASE_URL https://api.synthetic.new/anthropic; export const SYNTHETIC_DEFAULT_MODEL_ID hf:MiniMaxAI/MiniMax-M3; export const SYNTHETIC_DEFAULT_MODEL_REF synthetic/${SYNHETIC_DEFAULT_MODEL_ID};模型引用统一采用synthetic/modelId形式,例如synthetic/hf:MiniMaxAI/MiniMax-M3。若 Synthetic 端点发生迁移,覆盖models.providers.synthetic.baseUrl即可,OpenClaw 仍会自动补上/v1后缀。完整配置示例官方文档给出的完整 json5 配置如下(可直接对照使用,${SYNTHETIC_API_KEY}由env.vars注入):{ env: { vars: { SYNTHETIC_API_KEY: sk-... } }, agents: { defaults: { model: { primary: synthetic/hf:MiniMaxAI/MiniMax-M3 }, models: { synthetic/hf:MiniMaxAI/MiniMax-M3: { alias: MiniMax M3 } }, }, }, models: { mode: merge, providers: { synthetic: { baseUrl: https://api.synthetic.new/anthropic, apiKey: ${SYNTHETIC_API_KEY}, api: anthropic-messages, models: [ { id: hf:MiniMaxAI/MiniMax-M3, name: MiniMax M3, reasoning: true, input: [text, image], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 262144, maxTokens: 65536, }, ], }, }, }, }逐字段说明:env.vars.SYNTHETIC_API_KEY:API 密钥的唯一来源,配置中以${SYNTHETIC_API_KEY}插值引用;agents.defaults.model.primary:把 Synthetic 的默认模型设为 Agent 主模型;agents.defaults.models:为模型注册别名,便于在会话中引用;models.mode: merge:以合并模式覆盖内置目录,而非整体替换;models.providers.synthetic.baseUrl:推理端点,客户端会自动追加/v1;models.providers.synthetic.api: anthropic-messages:显式声明走 Anthropic Messages 协议;模型条目中reasoning: true表示支持推理输出,input: [text, image]表示支持图像输入,cost四项(每百万 token 计价)在种子目录中均为 0,实时发现时会被 Synthetic 上报的按用量价格替换;contextWindow: 262144与maxTokens: 65536分别是上下文窗口与单次最大输出长度。种子目录中除默认模型外,还内置了另外 6 个模型(见 models.ts 的SYNTHETIC_MODEL_CATALOG),涵盖 MiniMax M3、Kimi K2.7 Code、NVIDIA Nemotron 3 Super 120B、GPT OSS 120B、Qwen3.6 27B、GLM-4.7 Flash 与 GLM-5.2,上下文窗口从 131072 到 524288 不等,maxTokens从 8192 到 131072 不等,作为离线场景的兜底目录。模型发现:静态种子目录与实时目录这是 Synthetic 提供商区别于多数静态插件的关键设计,官方文档描述为:持有 Synthetic 凭据时,OpenClaw 会从 Synthetic 的 OpenAI 兼容/openai/v1/models接口发现当前可用的文本模型;推理仍然走 Anthropic Messages API;新上架的模型(包括小模型与syn:别名)无需等待 OpenClaw 目录更新即可被发现;实时目录提供上下文/输出上限、图像输入、推理能力、工具支持,以及基于用量的 token 价格——这些价格仅为估算,不代表订阅账单;离线生成目录、或发现响应不可用/不可用时,回退到内置种子模型;你已选择的模型不会被自动更改;当覆盖了推理 base URL 时,OpenClaw 会跳过 Synthetic 固定的发现 URL,避免把代理凭据发送到 Synthetic。发现端点的安全边界provider-catalog.ts 中的SYNTHETIC_MODEL_DISCOVERY明确了发现走 OpenAI 兼容接口、推理留在 Anthropic 端点的双轨结构:export const SYNTHETIC_MODEL_DISCOVERY: OpenAICompatibleModelDiscoveryOptions { // Discovery is OpenAI-compatible; inference stays on the Anthropic endpoint. // A custom proxys credential must never be forwarded to this vendor URL. endpointUrl: { url: https://api.synthetic.new/openai/v1/models, requireBaseUrl: SYNTHETIC_BASE_URL, }, projectRows: projectSyntheticModels, };requireBaseUrl: SYNTHETIC_BASE_URL就是文档中覆盖 base URL 时跳过固定发现 URL的源码实现:只有当配置的 base URL 恰好等于官方默认值时,才向 Synthetic 的固定发现端点发起请求;一旦用户把推理指向自建代理,发现请求即被跳过,代理凭据不会被转发给供应商。实时模型行的过滤与映射规则projectSyntheticModels函数定义了哪些模型会被纳入目录,以及元数据如何映射,规则相当严格:直接丢弃的行(不进入目录):无id,或id长度超过 512、包含空白/控制字符;context_length缺失或非正整数;input_modalities不含text,或output_modalities不含text(即纯 embedding 等模型被排除);deprecated true或active false(已弃用/停用的模型)。保留行的字段映射:name取响应中的name,缺失时回退为id;reasoning由supported_features含reasoning,或reasoning_parameters.efforts中存在非none的取值决定;input在input_modalities含image时映射为[text, image],否则为[text];maxTokens min(max_output_length, contextWindow),响应缺失输出上限时回退到种子目录同 id 的值,再缺失则取 8192;cost四项从pricing的prompt/completion/input_cache_reads/input_cache_writes解析:readTokenPrice先剥掉$前缀再乘以 1,000,000,即把每 token 美元价换算成 OpenClaw 配置的每百万 token 美元价,解析失败则回退种子目录值(默认 0);supported_features为数组时,额外写入compat.supportsTools(是否含tools);最终目录按id字典序排序输出,且实时数据拥有最终解释权——即使 id 在种子目录中,上下限与能力也以实时响应为准。测试用例 provider-catalog.test.ts 用一组构造数据验证了上述规则:8 条响应中,embedding 模型(output_modalities: [embedding])、非法上下文长度(context_length: -1)与弃用模型(deprecated: true)被过滤,syn:别名小模型在缺失max_output_length时正确回退到 8192,而新模型hf:moonshotai/Kimi-K3与已知模型hf:zai-org/GLM-5.2(输入模态被实时数据修正为纯文本)分别被新增与刷新;同时测试断言发现请求确实发往https://api.synthetic.new/openai/v1/models,且 Authorization 头携带的是专门的 discovery key——印证了发现凭据与推理凭据隔离的实现。模型允许列表(allowlist)如果你启用了模型允许列表(agents.defaults.modelPolicy.allow),需要把计划使用的每个 Synthetic 模型都加入其中,否则不在允许列表中的模型对 Agent 不可见。Base URL 覆盖若 Synthetic 变更了 API 端点,按以下方式覆盖 base URL:{ models: { providers: { synthetic: { baseUrl: https://new-api.synthetic.new/anthropic, }, }, }, }注意两点:OpenClaw 仍会自动追加/v1;按上文模型发现一节所述,覆盖 base URL 后固定的 Synthetic 发现端点将被跳过,模型目录将依赖种子目录或你的代理提供的能力。插件入口与目录刷新模式插件入口 index.ts 展示了完整的注册形态,几个值得注意的字段:catalog: { discoveryMode: strict, buildProvider: buildSyntheticProvider, buildStaticProvider: buildSyntheticProvider, allowExplicitBaseUrl: true, liveModelDiscovery: SYNTHETIC_MODEL_DISCOVERY, },discoveryMode: strict:目录构建以发现结果为准;buildProvider与buildStaticProvider指向同一实现 buildSyntheticProvider,后者返回{ baseUrl, api: anthropic-messages, models: 种子目录 },保证离线/静态场景与在线场景的 provider 形态一致;allowExplicitBaseUrl: true允许用户在配置中显式覆盖 base URL,配合SYNTHETIC_MODEL_DISCOVERY的requireBaseUrl约束,形成显式覆盖即跳过厂商发现的安全闭环;manifestAuth.applyConfig: applySyntheticConnectionConfig即 onboarding 写入连接的回调,来自 onboard.ts 中的预设应用器。相关文件索引内容路径官方提供商文档docs/providers/synthetic.md插件入口(provider 注册)extensions/synthetic/index.ts种子模型目录与常量extensions/synthetic/models.tsonboarding 预设应用器extensions/synthetic/onboard.ts实时发现端点与行映射extensions/synthetic/provider-catalog.ts发现逻辑测试extensions/synthetic/provider-catalog.test.ts插件清单(认证选项、目录刷新声明)extensions/synthetic/openclaw.plugin.json进一步阅读可参考仓库文档中的 Model providers(提供商规则、模型引用与故障转移行为)与 Configuration reference(含提供商设置的完整配置 schema),它们与本文的models.providers.synthetic配置节互为补充。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
