6.11 OpenAI兼容API - OpenClaw中文社区

OpenClaw Gateway 提供 OpenAI 兼容的 Chat Completions API 端点,允许使用标准的 OpenAI SDK 和工具与 OpenClaw 交互。

概述

OpenAI 兼容 API 通过 Gateway 的单端口多路复用 HTTP 服务器提供服务,默认端口为 18789。该端点位于 /v1/chat/completions,与其他 Gateway 端点(如 /v1/responses 和 /tools/invoke)共享同一 HTTP 服务。

重要

OpenAI Chat Completions 端点默认禁用。需要在配置中显式启用。

启用端点

在配置文件中启用 Chat Completions 端点:

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

认证配置

访问 OpenAI 兼容 API 需要配置 Gateway 认证。支持两种认证方式:

令牌认证

{
  "gateway": {
    "auth": {
      "token": "your-secure-token-here"
    }
  }
}

密码认证

{
  "gateway": {
    "auth": {
      "password": "your-secure-password"
    }
  }
}

注意

客户端必须在 WebSocket 握手时发送 connect.params.auth.token 或 connect.params.auth.password。不使用单独的 API 密钥头,认证通过 WebSocket 握手流程完成。

使用示例

配置启用后,可以使用任何支持 OpenAI API 的工具或 SDK:

使用 Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18789/v1",
    api_key="your-token-here"
)

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "Hello, OpenClaw!"}
    ]
)

print(response.choices[0].message.content)

使用 curl

# 发送 Chat Completion 请求
curl http://localhost:18789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

与自定义模型提供商集成

OpenClaw 支持通过自定义提供商配置连接到其他 OpenAI 兼容的服务:

LM Studio

{
  "models": {
    "providers": {
      "lmstudio": {
        "apiType": "openai",
        "baseUrl": "http://127.0.0.1:1234/v1",
        "models": {
          "default": "local-model"
        }
      }
    }
  }
}

其他兼容服务

{
  "models": {
    "providers": {
      "custom": {
        "apiType": "openai",
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "${CUSTOM_API_KEY}",
        "models": {
          "gpt-4": "custom-gpt-4"
        }
      }
    }
  }
}

端口说明

Gateway 使用单一端口 (默认 18789) 提供多个服务:

/v1/chat/completions - OpenAI 兼容 API
/v1/responses - OpenClaw Responses API
/tools/invoke - 工具调用端点
WebSocket 连接 - 节点到 Gateway 的 RPC 通信

安全建议

安全提示

保持 loopback 绑定: 默认 Gateway 仅监听 127.0.0.1,这是最安全的配置
使用强认证: 设置足够强度的 token 或 password
远程访问: 如需远程访问,建议使用 SSH 隧道或 Tailscale,而非直接暴露端口
环境变量: 敏感凭据使用环境变量,避免硬编码在配置文件中

常用命令

# 启动 Gateway 并指定端口
openclaw gateway --port 18789

# 检查 Gateway 状态
openclaw status

# 查看 Gateway 配置
openclaw config show

# 测试端点连接
curl http://localhost:18789/v1/chat/completions

故障排查

连接被拒绝: 检查 Gateway 是否运行 (openclaw status)
认证失败: 确认 gateway.auth.token 或 gateway.auth.password 已正确配置
端点未找到: 确认 gateway.http.endpoints.chatCompletions.enabled 已设为 true
端口冲突: 检查端口 18789 是否被其他进程占用

概述