在 OpenClaw 中接入自托管 SGLang模型自动发现、显式配置与代理式行为详解【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawSGLang 是当前主流的开源权重模型推理服务框架通过 OpenAI 兼容的 HTTP API/v1端点对外提供chat/completions与models等服务。本文基于 OpenClaw 仓库内建bundled的sglangprovider 插件完整讲解如何让 OpenClaw 连接本地或远程的 SGLang 服务器从环境变量与 base URL 的准备、openclaw onboard的引导接入到模型自动发现implicit provider discovery、显式声明模型的进阶配置以及 SGLang 作为代理式 OpenAI 兼容后端在请求整形上的特殊行为。读完本文你将能在自己的 OpenClaw 实例上以sglang/*模型引用方式动态或静态地使用自托管的开源模型。SGLang provider 概览OpenClaw 将 SGLang 视为一个自托管、OpenAI 兼容的 provider归属于openai-completionsprovider 家族。下表汇总了 docs/providers/sglang.md 中定义的核心属性属性值Provider idsglang插件形态bundledenabledByDefault: true认证环境变量SGLANG_API_KEY服务器无认证时任意非空值即可引导标志--auth-choice sglangAPIOpenAI 兼容openai-completions默认 base URLhttp://127.0.0.1:30000/v1默认模型占位符sglang/Qwen/Qwen3-8B流式 usage 支持是supportsStreamingUsage: true计费标记外部免费modelPricing.external: false这些默认值并非散落在文档中而是由插件源码直接定义。查看 extensions/sglang/defaults.ts 可以看到与文档一一对应的常量export const SGLANG_DEFAULT_BASE_URL http://127.0.0.1:30000/v1; export const SGLANG_PROVIDER_LABEL SGLang; export const SGLANG_DEFAULT_API_KEY_ENV_VAR SGLANG_API_KEY; export const SGLANG_MODEL_PLACEHOLDER Qwen/Qwen3-8B;同时插件的package.json见 extensions/sglang/openclaw.plugin.json通过modelCatalog: { discovery: { sglang: refreshable } }声明该 provider 的模型目录是可刷新的这正是自动发现能力的插件级契约providerRequest区块则声明supportsStreamingUsage: true即 SGLang 的流式响应会携带 token usage 统计。快速开始三步接入本地 SGLang第一步启动 SGLang 服务器SGLang 以 OpenAI 兼容模式启动后需要对外暴露/v1端点如/v1/models、/v1/chat/completions。常见默认地址为http://127.0.0.1:30000/v1OpenClaw 的默认 base URL 正是对应这个地址因此本机默认部署时无需任何额外配置。第二步设置 API KeySGLang 服务器若未启用认证任意非空值即可让 OpenClaw 通过认证检查并参与模型发现export SGLANG_API_KEYsglang-local第三步引导或手动指定模型运行交互式引导openclaw onboard在引导过程中选择 SGLang对应--auth-choice sglang标志OpenClaw 会自动写入认证 profile。也可以直接修改配置文件手动指定模型{ agents: { defaults: { model: { primary: sglang/your-model-id }, }, }, }这里的sglang/your-model-id采用provider/model-id的模型引用model ref语法其中模型 ID 应与 SGLang 实际加载的模型名一致。模型自动发现隐式 provider当满足以下两个条件时OpenClaw 会启用 SGLang 的模型自动发现SGLANG_API_KEY已设置或已存在对应 auth profile配置中没有显式定义models.providers.sglang。此时 OpenClaw 会向GET http://127.0.0.1:30000/v1/models发起请求并把返回的模型 ID 列表自动转换成可用的模型条目。这意味着你更换或新增 SGLang 加载的权重时无需修改 OpenClaw 配置即可使用新模型。注意一旦你显式定义了models.providers.sglangOpenClaw 默认只会使用你在配置中声明的模型列表。若仍希望动态包含该 provider 在/models端点下公布的全部模型请在agents.defaults.models中加入sglang/*: {}星号通配将发现模式保持为动态。详见 docs/providers/sglang.md。这一发现机制在插件侧由openclaw.plugin.json的modelCatalog.discovery.sglang refreshable声明并由 extensions/sglang/provider-discovery.contract.test.ts 通过describeSglangProviderDiscoveryContract契约测试加以验证——该测试加载插件的index.js与api.js断言发现行为符合 provider 契约。测试代码见 extensions/sglang/index.test.ts其中还验证了 SGLang 插件构建的 replay policy 包含sanitizeToolCallIds、toolCallIdMode: strict、applyAssistantFirstOrderingFix、validateGeminiTurns、validateAnthropicTurns等属性且不会dropReasoningFromHistory——也就是说即使接入的是带思考链reasoning的模型如 Kimi K2 之类OpenClaw 回放历史时也不会丢弃其推理内容。显式配置手动声明模型当以下任一情况出现时推荐使用显式配置SGLang 运行在不同的主机或端口上需要固定contextWindow/maxTokens等模型参数服务器要求真实 API Key或需要控制请求头。完整配置示例如下与 docs/providers/sglang.md 一致并补充注释{ models: { providers: { sglang: { // 自定义地址远程主机、非默认端口时修改这里 baseUrl: http://127.0.0.1:30000/v1, // 引用环境变量服务器无认证时也可直接写任意字符串 apiKey: ${SGLANG_API_KEY}, // 声明为 OpenAI 兼容 completion 风格 API api: openai-completions, models: [ { // 与 SGLang 实际加载的模型 ID 保持一致 id: your-model-id, // 在模型选择器 / 对话中展示的名字 name: Local SGLang Model, // 非推理模型若加载了带 reasoning 的模型应改为 true reasoning: false, // 输入模态文本 input: [text], // 自托管无计费所有成本项置 0 cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, // 上下文窗口长度token contextWindow: 128000, // 单次最大生成 token 数 maxTokens: 8192, }, ], }, }, }, }参数含义速览baseUrlSGLang 的/v1服务地址可指向任意可达的主机apiKey支持${ENV_VAR}形式的变量插值api固定为openai-completions表示走 OpenAI 兼容请求整形models[].reasoning标记该模型是否输出思考链影响 OpenClaw 对请求/回放的整形策略models[].cost自托管场景下通常全为 0OpenClaw 据此做成本预估与路由决策models[].contextWindow/maxTokens分别约束输入窗口与输出上限避免超长请求打爆本地显存。高级配置代理式行为与排查代理式proxy-style行为OpenClaw 将 SGLang 视为代理式的 OpenAI 兼容/v1后端而不是原生 OpenAI 端点因此部分 OpenAI 专属行为不会被应用。下表来自 docs/providers/sglang.md行为SGLangOpenAI-only 请求整形不应用service_tier、Responsesstore、prompt-cache 提示不发送推理兼容reasoning-compat请求整形不应用隐藏归属请求头originator、version、User-Agent在自定义 SGLang base URL 上不注入从源码实现看extensions/sglang/index.ts 使用 SDK 的defineSelfHostedOpenAICompatibleProvider构造插件并通过buildProviderReplayFamilyHooks({ family: openai-compatible, dropReasoningFromHistory: false })把 replay 行为归入openai-compatible家族、且保留推理历史——这与 extensions/sglang/index.test.ts 中断言的策略完全一致。排查指南服务器不可达先用 curl 直接验证 SGLang 的/v1/models是否响应curl http://127.0.0.1:30000/v1/models若超时或连接被拒请检查 SGLang 进程是否存活、端口是否正确、防火墙/网络策略是否放行。认证错误如果请求因认证失败请设置与服务器配置匹配的真实SGLANG_API_KEY或在models.providers.sglang下显式配置 apiKey。提示若你的 SGLang 未启用认证SGLANG_API_KEY取任意非空值即可满足 opt-in 条件、启用模型自动发现。与相关文档的衔接关于 provider 选择、模型引用语法与故障转移failover行为参考 模型选择概念文档关于 provider 条目的完整配置 schema参考 配置参考SGLang 插件的实现与测试位于 extensions/sglang其中openclaw.plugin.json声明了 provider 家族、发现刷新策略、流式 usage 与计费标记是理解该 provider 契约的最直接入口。小结SGLang provider 是 OpenClaw 在本地/自托管开源模型场景下的低成本接入方案默认地址开箱即用SGLANG_API_KEY一键开启模型自动发现显式配置则适合跨主机部署与参数固化场景。理解其代理式 OpenAI 兼容后端的定位能帮助你在接入带推理能力或特殊请求头的模型时准确预期 OpenClaw 的请求整形行为避免在排查环节走弯路。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 OpenClaw 中接入自托管 SGLang：模型自动发现、显式配置与代理式行为详解
在 OpenClaw 中接入自托管 SGLang模型自动发现、显式配置与代理式行为详解【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawSGLang 是当前主流的开源权重模型推理服务框架通过 OpenAI 兼容的 HTTP API/v1端点对外提供chat/completions与models等服务。本文基于 OpenClaw 仓库内建bundled的sglangprovider 插件完整讲解如何让 OpenClaw 连接本地或远程的 SGLang 服务器从环境变量与 base URL 的准备、openclaw onboard的引导接入到模型自动发现implicit provider discovery、显式声明模型的进阶配置以及 SGLang 作为代理式 OpenAI 兼容后端在请求整形上的特殊行为。读完本文你将能在自己的 OpenClaw 实例上以sglang/*模型引用方式动态或静态地使用自托管的开源模型。SGLang provider 概览OpenClaw 将 SGLang 视为一个自托管、OpenAI 兼容的 provider归属于openai-completionsprovider 家族。下表汇总了 docs/providers/sglang.md 中定义的核心属性属性值Provider idsglang插件形态bundledenabledByDefault: true认证环境变量SGLANG_API_KEY服务器无认证时任意非空值即可引导标志--auth-choice sglangAPIOpenAI 兼容openai-completions默认 base URLhttp://127.0.0.1:30000/v1默认模型占位符sglang/Qwen/Qwen3-8B流式 usage 支持是supportsStreamingUsage: true计费标记外部免费modelPricing.external: false这些默认值并非散落在文档中而是由插件源码直接定义。查看 extensions/sglang/defaults.ts 可以看到与文档一一对应的常量export const SGLANG_DEFAULT_BASE_URL http://127.0.0.1:30000/v1; export const SGLANG_PROVIDER_LABEL SGLang; export const SGLANG_DEFAULT_API_KEY_ENV_VAR SGLANG_API_KEY; export const SGLANG_MODEL_PLACEHOLDER Qwen/Qwen3-8B;同时插件的package.json见 extensions/sglang/openclaw.plugin.json通过modelCatalog: { discovery: { sglang: refreshable } }声明该 provider 的模型目录是可刷新的这正是自动发现能力的插件级契约providerRequest区块则声明supportsStreamingUsage: true即 SGLang 的流式响应会携带 token usage 统计。快速开始三步接入本地 SGLang第一步启动 SGLang 服务器SGLang 以 OpenAI 兼容模式启动后需要对外暴露/v1端点如/v1/models、/v1/chat/completions。常见默认地址为http://127.0.0.1:30000/v1OpenClaw 的默认 base URL 正是对应这个地址因此本机默认部署时无需任何额外配置。第二步设置 API KeySGLang 服务器若未启用认证任意非空值即可让 OpenClaw 通过认证检查并参与模型发现export SGLANG_API_KEYsglang-local第三步引导或手动指定模型运行交互式引导openclaw onboard在引导过程中选择 SGLang对应--auth-choice sglang标志OpenClaw 会自动写入认证 profile。也可以直接修改配置文件手动指定模型{ agents: { defaults: { model: { primary: sglang/your-model-id }, }, }, }这里的sglang/your-model-id采用provider/model-id的模型引用model ref语法其中模型 ID 应与 SGLang 实际加载的模型名一致。模型自动发现隐式 provider当满足以下两个条件时OpenClaw 会启用 SGLang 的模型自动发现SGLANG_API_KEY已设置或已存在对应 auth profile配置中没有显式定义models.providers.sglang。此时 OpenClaw 会向GET http://127.0.0.1:30000/v1/models发起请求并把返回的模型 ID 列表自动转换成可用的模型条目。这意味着你更换或新增 SGLang 加载的权重时无需修改 OpenClaw 配置即可使用新模型。注意一旦你显式定义了models.providers.sglangOpenClaw 默认只会使用你在配置中声明的模型列表。若仍希望动态包含该 provider 在/models端点下公布的全部模型请在agents.defaults.models中加入sglang/*: {}星号通配将发现模式保持为动态。详见 docs/providers/sglang.md。这一发现机制在插件侧由openclaw.plugin.json的modelCatalog.discovery.sglang refreshable声明并由 extensions/sglang/provider-discovery.contract.test.ts 通过describeSglangProviderDiscoveryContract契约测试加以验证——该测试加载插件的index.js与api.js断言发现行为符合 provider 契约。测试代码见 extensions/sglang/index.test.ts其中还验证了 SGLang 插件构建的 replay policy 包含sanitizeToolCallIds、toolCallIdMode: strict、applyAssistantFirstOrderingFix、validateGeminiTurns、validateAnthropicTurns等属性且不会dropReasoningFromHistory——也就是说即使接入的是带思考链reasoning的模型如 Kimi K2 之类OpenClaw 回放历史时也不会丢弃其推理内容。显式配置手动声明模型当以下任一情况出现时推荐使用显式配置SGLang 运行在不同的主机或端口上需要固定contextWindow/maxTokens等模型参数服务器要求真实 API Key或需要控制请求头。完整配置示例如下与 docs/providers/sglang.md 一致并补充注释{ models: { providers: { sglang: { // 自定义地址远程主机、非默认端口时修改这里 baseUrl: http://127.0.0.1:30000/v1, // 引用环境变量服务器无认证时也可直接写任意字符串 apiKey: ${SGLANG_API_KEY}, // 声明为 OpenAI 兼容 completion 风格 API api: openai-completions, models: [ { // 与 SGLang 实际加载的模型 ID 保持一致 id: your-model-id, // 在模型选择器 / 对话中展示的名字 name: Local SGLang Model, // 非推理模型若加载了带 reasoning 的模型应改为 true reasoning: false, // 输入模态文本 input: [text], // 自托管无计费所有成本项置 0 cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, // 上下文窗口长度token contextWindow: 128000, // 单次最大生成 token 数 maxTokens: 8192, }, ], }, }, }, }参数含义速览baseUrlSGLang 的/v1服务地址可指向任意可达的主机apiKey支持${ENV_VAR}形式的变量插值api固定为openai-completions表示走 OpenAI 兼容请求整形models[].reasoning标记该模型是否输出思考链影响 OpenClaw 对请求/回放的整形策略models[].cost自托管场景下通常全为 0OpenClaw 据此做成本预估与路由决策models[].contextWindow/maxTokens分别约束输入窗口与输出上限避免超长请求打爆本地显存。高级配置代理式行为与排查代理式proxy-style行为OpenClaw 将 SGLang 视为代理式的 OpenAI 兼容/v1后端而不是原生 OpenAI 端点因此部分 OpenAI 专属行为不会被应用。下表来自 docs/providers/sglang.md行为SGLangOpenAI-only 请求整形不应用service_tier、Responsesstore、prompt-cache 提示不发送推理兼容reasoning-compat请求整形不应用隐藏归属请求头originator、version、User-Agent在自定义 SGLang base URL 上不注入从源码实现看extensions/sglang/index.ts 使用 SDK 的defineSelfHostedOpenAICompatibleProvider构造插件并通过buildProviderReplayFamilyHooks({ family: openai-compatible, dropReasoningFromHistory: false })把 replay 行为归入openai-compatible家族、且保留推理历史——这与 extensions/sglang/index.test.ts 中断言的策略完全一致。排查指南服务器不可达先用 curl 直接验证 SGLang 的/v1/models是否响应curl http://127.0.0.1:30000/v1/models若超时或连接被拒请检查 SGLang 进程是否存活、端口是否正确、防火墙/网络策略是否放行。认证错误如果请求因认证失败请设置与服务器配置匹配的真实SGLANG_API_KEY或在models.providers.sglang下显式配置 apiKey。提示若你的 SGLang 未启用认证SGLANG_API_KEY取任意非空值即可满足 opt-in 条件、启用模型自动发现。与相关文档的衔接关于 provider 选择、模型引用语法与故障转移failover行为参考 模型选择概念文档关于 provider 条目的完整配置 schema参考 配置参考SGLang 插件的实现与测试位于 extensions/sglang其中openclaw.plugin.json声明了 provider 家族、发现刷新策略、流式 usage 与计费标记是理解该 provider 契约的最直接入口。小结SGLang provider 是 OpenClaw 在本地/自托管开源模型场景下的低成本接入方案默认地址开箱即用SGLANG_API_KEY一键开启模型自动发现显式配置则适合跨主机部署与参数固化场景。理解其代理式 OpenAI 兼容后端的定位能帮助你在接入带推理能力或特殊请求头的模型时准确预期 OpenClaw 的请求整形行为避免在排查环节走弯路。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
