企业官网建设流程全解析

在 OpenClaw 中接入自托管 SGLang：模型自动发现、显式配置与代理式行为详解

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

SGLang 是当前主流的开源权重模型推理服务框架，通过 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 中定义的核心属性：

这些默认值并非散落在文档中，而是由插件源码直接定义。查看 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/v1

OpenClaw 的默认 base URL 正是对应这个地址，因此本机默认部署时无需任何额外配置。

第二步：设置 API Key

SGLang 服务器若未启用认证，任意非空值即可让 OpenClaw 通过认证检查并参与模型发现：

export SGLANG_API_KEY="sglang-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 的模型自动发现：

1. SGLANG_API_KEY已设置（或已存在对应 auth profile）；
2. 配置中没有显式定义models.providers.sglang。

此时 OpenClaw 会向

GET http://127.0.0.1:30000/v1/models

发起请求，并把返回的模型 ID 列表自动转换成可用的模型条目。这意味着你更换或新增 SGLang 加载的权重时，无需修改 OpenClaw 配置即可使用新模型。

注意：一旦你显式定义了models.providers.sglang，OpenClaw 默认只会使用你在配置中声明的模型列表。若仍希望动态包含该 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, }, ], }, }, }, }

参数含义速览：

• baseUrl：SGLang 的/v1服务地址，可指向任意可达的主机；
• apiKey：支持${ENV_VAR}形式的变量插值；
• api：固定为openai-completions，表示走 OpenAI 兼容请求整形；
• models[].reasoning：标记该模型是否输出思考链，影响 OpenClaw 对请求/回放的整形策略；
• models[].cost：自托管场景下通常全为 0，OpenClaw 据此做成本预估与路由决策；
• models[].contextWindow/maxTokens：分别约束输入窗口与输出上限，避免超长请求打爆本地显存。

高级配置：代理式行为与排查

代理式（proxy-style）行为

OpenClaw 将 SGLang 视为"代理式"的 OpenAI 兼容/v1后端，而不是原生 OpenAI 端点，因此部分 OpenAI 专属行为不会被应用。下表来自 docs/providers/sglang.md：

从源码实现看，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