OpenClaw 通过 OpenAI 兼容的 /v1 接口接入自托管的 SGLang 推理服务。设置 SGLANG_API_KEY（不限值）即可触发模型自动发现，无需手动声明模型列表；若需固定上下文窗口、运行在不同端口或添加真实鉴权，可显式配置 models.providers.sglang。默认 base URL 为 http://127.0.0.1:30000/v1，流式输出和定价标记为外部免费均内置支持。排查时用 curl http://127.0.0.1:30000/v1/models 验证服务可达性。

OpenClaw SGLang 配置：本地模型接入与自动发现

SGLang 可通过 OpenAI 兼容的 HTTP API 运行开源权重模型。OpenClaw 使用 openai-completions provider 连接 SGLang，并支持自动发现可用模型。

属性	值
Provider id	sglang
插件	内置，enabledByDefault: true
认证环境变量	SGLANG_API_KEY（若服务器无认证可填任意非空值）
引导标志	--auth-choice sglang
API	OpenAI 兼容（openai-completions）
默认 base URL	http://127.0.0.1:30000/v1
默认模型占位符	sglang/Qwen/Qwen3-8B
流式输出	支持（supportsStreamingUsage: true）
定价	标记为外部免费（modelPricing.external: false）

设置 SGLANG_API_KEY 后，OpenClaw 会自动从 SGLang 查询可用模型。若你也配置了自定义 base URL，可在 agents.defaults.models 中使用 sglang/* 保持动态发现。详见下方模型自动发现（隐式 Provider）。

快速上手

1. 启动 SGLang 服务器
   确保 base URL 暴露 /v1 端点（如 /v1/models、/v1/chat/completions）。SGLang 通常运行在：
   http://127.0.0.1:30000/v1

2. 设置 API Key
   如果服务器未启用认证，任意值即可：

   export SGLANG_API_KEY="sglang-local"

3. 运行引导或直接指定模型

   openclaw onboard

   或手动配置：

   {
     agents: {
       defaults: {
         model: { primary: "sglang/your-model-id" },
       },
     },
   }

模型自动发现（隐式 Provider）

当 SGLANG_API_KEY 已设置（或存在 auth profile）且你没有定义 models.providers.sglang 时，OpenClaw 会自动查询：

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

并将返回的模型 ID 转换为可用模型条目。

INFO

若显式定义了 models.providers.sglang，OpenClaw 默认使用你声明的模型。如需让 OpenClaw 仍然查询该 provider 的 /models 端点并包含所有 SGLang 模型，可在 agents.defaults.models 中添加 "sglang/*": {}。

显式配置（手动模型）

以下场景建议使用显式配置：

• SGLang 运行在不同主机/端口
• 需要固定 contextWindow / maxTokens 值
• 服务器要求真实 API Key，或需要控制请求头

{
  models: {
    providers: {
      sglang: {
        baseUrl: "http://127.0.0.1:30000/v1",
        apiKey: "${SGLANG_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "your-model-id",
            name: "Local SGLang Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

高级配置

代理风格行为

SGLang 被视为代理风格的 OpenAI 兼容 /v1 后端，并非原生 OpenAI 端点。

行为	SGLang
OpenAI 专用请求整形	不应用
service_tier、Responses store、prompt-cache 提示	不发送
推理兼容性负载整形	不应用
隐藏的归属标头（originator、version、User-Agent）	自定义 SGLang base URL 时不注入

故障排查

服务器不可达

验证服务器运行并响应：

curl http://127.0.0.1:30000/v1/models

认证错误

若请求因认证失败，请设置与服务器配置一致的 SGLANG_API_KEY，或在 models.providers.sglang 下显式配置 provider。

TIP

如果 SGLang 未启用认证，SGLANG_API_KEY 填任意非空值即可触发模型自动发现。

相关文档

• 模型选择 – 选择 provider、模型引用和回退策略。
• 配置参考 – 包含 provider 条目的完整配置 schema。

常见问题

自动发现到一半不出现模型怎么办？

先确认 SGLang 服务器在运行且 /v1/models 可访问：curl http://127.0.0.1:30000/v1/models。其次检查是否显式定义了 models.providers.sglang——一旦定义，自动发现关闭，需手动添加模型或使用 "sglang/*": {} 重新启用发现。

SGLang 服务器需要真实 API Key，怎么配置？

在显式配置中设置 apiKey 引用环境变量，例如 "${SGLANG_API_KEY}"，并确保环境变量值与服务器要求的 key 一致。同时将 baseUrl 改为你的服务器地址（非默认端口时也需调整）。

报 auth 错误，明明没配置认证？

即使 SGLang 无认证，OpenClaw 仍要求 SGLANG_API_KEY 为非空字符串来触发 provider 注册。若未设置该变量，OpenClaw 无法识别 SGLang provider，导致请求发送到未认证端点时可能被其他中间件拦截。设置任意值（如 "skip"）即可。