如何调用OpenClaw API？Postman 请求示例详解

OpenClaw作为一个开源的个人 AI 代理工具，不仅支持本地部署和多渠道聊天，还提供了灵活的 API 接口，便于开发者进行二次集成、自动化任务调用或构建自定义客户端。通过 OpenClaw 的 Gateway API，你可以实现消息发送、会话管理、模型调用、文件操作等多种功能。本文将详细介绍 OpenClaw API 的调用方式，并以 Postman 为例，提供完整的请求配置和实战示例，帮助你快速上手。

文章导航

一、OpenClaw API 概述

OpenClaw 的核心服务是 Gateway，通常运行在本地或服务器的 18789 端口（默认 ws://127.0.0.1:18789 或 http://127.0.0.1:18789）。API 主要分为两类：

WebSocket API：用于实时双向通信，适合聊天、流式响应、主动推送等场景，是 ClawdBot 最常用的交互方式。
HTTP REST API：提供部分管理功能，如健康检查、会话列表、模型状态查询等，方便监控和集成。

官方文档中对 API 的描述较为简洁，但结合实际部署经验，Gateway 支持 OpenAI-compatible 的消息接口，同时提供原生的 OpenClaw 专属端点。调用前需确保：

OpenClaw 已正常启动（openclaw gateway status 显示 active）。
如果是远程调用，需要通过 SSH 隧道、Cloudflare Tunnel 或内网穿透暴露端口。
部分接口需要认证（设备配对码或 API Key，视配置而定）。

二、准备工作：部署并启动 OpenClaw Gateway

在调用 API 前，必须先完成 OpenClaw 的部署和 Gateway 启动。以下是简要步骤（完整部署可参考官方一键脚本）：

一键安装（Linux/macOS）：
bash curl -fsSL https://clawd.bot/install.sh | bash
启动配置向导：
bash clawdbot onboard --install-daemon
按提示配置模型（推荐 Claude 或 GLM-4）、聊天渠道和 Skills。
启动 Gateway 服务：
bash systemctl --user start clawdbot-gateway.service systemctl --user status clawdbot-gateway.service
确认输出包含 Active: active (running) 和 ws://127.0.0.1:18789。
设备配对（首次调用必须）：
通过 Telegram/WhatsApp 发送任意消息获取配对码，然后执行：
bash clawdbot pairing approve telegram <配对码>

完成后，API 即可使用。建议在本地测试，远程访问时使用 SSH 隧道：

ssh -L 18789:127.0.0.1:18789 user@your-server-ip

三、Postman 配置基础

Postman 是调用 REST 和 WebSocket API 的绝佳工具。以下是通用配置步骤：

新建 Collection，命名为 “ClawdBot API”。
设置 Collection 变量（Variables）：
- base_url：http://127.0.0.1:18789（HTTP）或 ws://127.0.0.1:18789（WebSocket）
- api_key：如果配置了自定义认证，可填写（默认无）
- profile：默认 default 或你的 agent 名称
对于需要认证的请求，在 Headers 中添加：
- Authorization: Bearer {{device_token}}（设备配对后可从日志获取）

四、HTTP REST API 常用端点及 Postman 示例

OpenClaw 提供了一系列 HTTP 端点，用于状态查询和管理。

1. 健康检查（GET /health）

最简单的接口，用于确认服务是否正常。

Postman 配置：
– 方法：GET
– URL：{{base_url}}/health

预期响应：

{
  "status": "ok",
  "version": "2026.1.29-1",
  "gateway": "running"
}

2. 获取模型列表（GET /v1/models）

兼容 OpenAI 格式，返回可用模型。

Postman 配置：
– 方法：GET
– URL：{{base_url}}/v1/models
– Headers：Content-Type: application/json

示例响应：

{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-opus-4-5-20251101",
      "object": "model",
      "created": 1735680000,
      "owned_by": "anthropic"
    },
    {
      "id": "z.ai/glm-4.7",
      "object": "model",
      "created": 1735680000,
      "owned_by": "z.ai"
    }
  ]
}

3. 发送消息（POST /v1/chat/completions）

最核心的接口，兼容 OpenAI Chat Completions 格式，支持流式和非流式。

Postman 配置：
– 方法：POST
– URL：{{base_url}}/v1/chat/completions
– Headers：
– Content-Type: application/json
– Body（raw JSON）：

{
  "model": "anthropic/claude-opus-4-5-20251101",
  "messages": [
    {
      "role": "user",
      "content": "帮我写一个 Python 脚本，爬取豆瓣电影 Top 250"
    }
  ],
  "stream": false,
  "max_tokens": 2048,
  "temperature": 0.7,
  "profile": "default"
}

非流式响应示例：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1735699200,
  "model": "anthropic/claude-opus-4-5-20251101",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "以下是完整的 Python 脚本..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 512,
    "total_tokens": 537
  }
}

开启流式（stream: true）：
响应会以 text/event-stream 格式逐块返回，Postman 会自动显示流式输出。

4. 会话管理接口

端点	方法	描述	参数示例
`/v1/agents`	GET	列出所有 agent/profile	无
`/v1/agents/{profile}/sessions`	GET	获取指定 profile 的会话列表	profile=default
`/v1/agents/{profile}/sessions/{session_id}`	DELETE	删除指定会话	session_id=abc123

Postman 示例（删除会话）：
– 方法：DELETE
– URL：{{base_url}}/v1/agents/default/sessions/abc123

五、WebSocket API 实战（实时聊天）

WebSocket 是 OpenClaw 最强大的交互方式，支持多轮对话、工具调用、主动推送。

1. Postman WebSocket 配置步骤

在 Postman 中新建 WebSocket Request。
URL：ws://127.0.0.1:18789/ws?profile=default
连接后发送 JSON 消息（Message 面板）。

2. 消息格式

OpenClaw WebSocket 采用标准 JSON 帧，核心字段：

{
  "type": "message",
  "profile": "default",
  "content": "你好，今天天气怎么样？",
  "session_id": "optional-session-id",
  "attachments": [] 
}

3. 完整交互示例

连接：Postman 自动连接 ws URL。
发送首条消息：

{
  "type": "message",
  "profile": "default",
  "content": "帮我搜索最近的 AI 新闻，总结 3 条"
}

接收响应：Postman 会实时显示服务端推送的多个帧，最终合成完整回复。
多轮对话：直接继续发送下一条消息，OpenClaw 会自动保持上下文。

支持的 type 类型表：

type	描述	适用场景
message	普通文本消息	日常聊天、指令
tool_call	工具调用请求	文件操作、浏览器自动化
heartbeat	心跳保活	长连接保持
session_create	创建新会话	隔离不同任务

六、高级用法：工具调用与文件上传

OpenClaw 支持强大的工具链（Skills），通过 API 可直接触发。

示例：浏览器自动化（POST /v1/chat/completions + tools）

Body 中加入 tools 数组：

{
  "model": "anthropic/claude-opus-4-5-20251101",
  "messages": [{"role": "user", "content": "帮我登录 GitHub 查看我的仓库"}],
  "tools": [{"type": "browser"}],
  "stream": true
}

OpenClaw 会自动返回 tool_call 帧，Postman 流式面板可实时查看执行进度。

文件上传示例（multipart/form-data）：
使用 POST /v1/files/upload，然后在消息中引用 file_id。