OpenClaw作为API网关：HTTP接口调用指南

前言

OpenClaw 不仅仅是一个聊天机器人框架——它本质上是一个 AI Agent 网关。除了通过 Telegram、Discord 等聊天平台与 AI 交互外，OpenClaw 还暴露了一套完整的 HTTP API 接口，允许你从任何应用程序、脚本或服务中以编程方式调用 AI Agent。

本文将系统介绍 OpenClaw 的 HTTP API 架构、认证方式、核心端点以及实际集成场景。

启用 API 网关

默认情况下，OpenClaw 启动时会同时启动一个 HTTP 服务器。你可以在 openclaw.json5 中配置网关参数：

{
  gateway: {
    // HTTP 服务监听端口
    port: 3000,
    // 监听地址，0.0.0.0 表示允许外部访问
    host: "0.0.0.0",
    // 是否启用 API 接口
    apiEnabled: true,
    // API 密钥认证
    apiKeys: [
      "sk-openclaw-xxxxxxxxxxxx",
      "sk-openclaw-yyyyyyyyyyyy"
    ],
    // 跨域配置
    cors: {
      origins: ["https://your-app.com"],
      methods: ["GET", "POST", "PUT", "DELETE"]
    }
  }
}

启用后，API 网关将在指定端口上提供 RESTful 接口。

认证方式

所有 API 请求都需要携带认证信息。OpenClaw 支持两种认证方式：

Bearer Token 认证

curl -X POST http://localhost:3000/api/v1/chat \
  -H "Authorization: Bearer sk-openclaw-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "你好"}'

查询参数认证

curl "http://localhost:3000/api/v1/agents?api_key=sk-openclaw-xxxxxxxxxxxx"

推荐使用 Bearer Token 方式，避免 API 密钥出现在 URL 日志中。

核心 API 端点

1. 发送消息

这是最常用的端点，向指定 Agent 发送消息并获取 AI 回复。

POST /api/v1/chat

请求体：

{
  "agentId": "my-agent",
  "sessionId": "session-001",
  "message": "帮我写一段排序算法",
  "stream": false
}

响应体：

{
  "status": "ok",
  "response": {
    "content": "这里是AI的回复内容...",
    "messageId": "msg_abc123",
    "model": "claude-sonnet-4-20250514",
    "usage": {
      "inputTokens": 150,
      "outputTokens": 320
    }
  }
}

2. 流式响应

对于长回复，建议使用 Server-Sent Events (SSE) 模式获取流式输出：

POST /api/v1/chat/stream

curl -N -X POST http://localhost:3000/api/v1/chat/stream \
  -H "Authorization: Bearer sk-openclaw-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "my-agent", "message": "详细解释快速排序"}'

返回的 SSE 事件流：

data: {"type":"start","messageId":"msg_def456"}

data: {"type":"text","content":"快速排序"}
data: {"type":"text","content":"（Quick Sort）"}
data: {"type":"text","content":"是一种高效的排序算法..."}

data: {"type":"tool_use","name":"run_code","input":{"code":"..."}}
data: {"type":"tool_result","output":"排序结果: [1, 2, 3, 5, 8]"}

data: {"type":"end","usage":{"inputTokens":85,"outputTokens":540}}

3. 管理会话

# 列出某Agent的所有活跃会话
GET /api/v1/agents/{agentId}/sessions

# 获取会话详情（包含消息历史）
GET /api/v1/agents/{agentId}/sessions/{sessionId}

# 删除某个会话
DELETE /api/v1/agents/{agentId}/sessions/{sessionId}

# 清除会话的历史消息
POST /api/v1/agents/{agentId}/sessions/{sessionId}/clear

4. 查询 Agent 信息

# 列出所有Agent
GET /api/v1/agents

# 获取单个Agent详情
GET /api/v1/agents/{agentId}

# 获取Agent的工具列表
GET /api/v1/agents/{agentId}/tools

5. 系统状态

# 健康检查
GET /api/v1/health

# 系统指标
GET /api/v1/metrics

实际集成示例

Python 集成

import requests

class OpenClawClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def chat(self, agent_id, message, session_id=None):
        resp = requests.post(
            f"{self.base_url}/api/v1/chat",
            headers=self.headers,
            json={
                "agentId": agent_id,
                "sessionId": session_id,
                "message": message
            }
        )
        return resp.json()["response"]["content"]

client = OpenClawClient("http://localhost:3000", "sk-openclaw-xxx")
reply = client.chat("my-agent", "今天天气怎么样？")
print(reply)

Node.js 集成

const response = await fetch("http://localhost:3000/api/v1/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-openclaw-xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agentId: "my-agent",
    message: "帮我分析这段代码"
  })
});

const data = await response.json();
console.log(data.response.content);

与前端应用集成

OpenClaw 的流式 API 可以直接用于构建自定义聊天界面：

const eventSource = new EventSource(
  "http://localhost:3000/api/v1/chat/stream?" +
  "agentId=my-agent&message=你好&api_key=sk-openclaw-xxx"
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "text") {
    appendToChat(data.content);
  }
};

速率限制与配额

API 网关内置了速率限制功能，防止滥用：

{
  gateway: {
    rateLimit: {
      // 每分钟最大请求数
      maxRequestsPerMinute: 60,
      // 每日最大Token消耗
      maxTokensPerDay: 1000000,
      // 按API Key独立计算
      perKey: true
    }
  }
}

超出限制时，API 返回 429 Too Many Requests 状态码。

与 OpenAI 兼容模式

OpenClaw 提供了 OpenAI 兼容的 API 端点，让你可以直接使用 OpenAI SDK 连接 OpenClaw：

POST /api/v1/openai/chat/completions

这意味着任何支持 OpenAI API 的客户端工具都可以无缝接入 OpenClaw，只需将 base_url 指向你的 OpenClaw 网关地址即可。

小结

OpenClaw 的 HTTP API 网关将 AI Agent 的能力以标准化接口的形式暴露出来，让你可以将 OpenClaw 集成到任何技术栈中——无论是 Web 应用、移动端、自动化脚本还是企业内部系统。结合流式响应、会话管理和 OpenAI 兼容模式，OpenClaw 能够胜任从简单聊天到复杂工作流的各种 API 网关场景。