Openclaw Sdk

OpenClaw SDK 使用指南

本 skill 是 AI Coding Reference：当 AI Agent 需要为用户编写使用 openclaw-sdk 的代码时，查阅本 skill 获取正确的 API 用法和经过测试的代码示例。

所有代码示例都经过真实 gateway 测试。

快速概览

openclaw-sdk 提供 Pythonic 接口连接 OpenClaw autonomous AI agent 框架。核心功能：

核心概念

Gateway 连接模式

SDK 支持三种 gateway 连接方式：

# 方式 1: 自动检测 (默认)
client = await OpenClawClient.from_env()

# 方式 2: WebSocket (ProtocolGateway)
client = await OpenClawClient.connect(
    gateway_ws_url="ws://127.0.0.1:18789/gateway"
)

# 方式 3: OpenAI 兼容 HTTP (无 WebSocket)
client = await OpenClawClient.connect(
    openai_base_url="https://api.openclaw.example/v1"
)

认证

Token 从环境变量 OPENCLAW_GATEWAY_TOKEN 或 ~/.openclaw/openclaw.json 读取。

核心使用模式

1. 连接并创建 Agent

from openclaw_sdk import OpenClawClient, AgentConfig

# 连接
client = await OpenClawClient.from_env()

# 创建 agent
agent = await client.create_agent(
    config=AgentConfig(
        agent_id="my-agent",
        name="My Assistant",
        system_prompt="你是一个有用的助手。",
        llm_model="claude-sonnet-4-20250514"
    )
)

2. 执行查询（同步）

result = await agent.execute("你好，请介绍一下你自己")
print(result.content)        # str: 文本内容
print(result.success)       # bool: 是否成功
print(result.token_usage)    # TokenUsage: token 消耗
print(result.files)         # list[GeneratedFile]: 生成的文件

3. 流式执行

async for event in agent.execute_stream("写一首关于月亮的诗"):
    if event.event_type == EventType.CONTENT:
        print(event.text, end="", flush=True)
    elif event.event_type == EventType.THINKING:
        print(f"[思考中...]{event.thinking}")
    elif event.event_type == EventType.TOOL_CALL:
        print(f"[工具调用: {event.tool} => {event.input}]")
    elif event.event_type == EventType.DONE:
        print(f"\n[完成: {event.stop_reason}]")

4. 批量执行

results = await agent.batch([
    "1 + 1 等于多少？",
    "世界上最深的海是什么？",
    "Python 的创始人是谁？"
])
for r in results:
    print(r.content)

5. 结构化输出（Pydantic）

from pydantic import BaseModel
from openclaw_sdk import OpenClawClient

client = await OpenClawClient.from_env()
agent = client.get_agent("my-agent")

class WeatherResult(BaseModel):
    city: str
    temperature: float
    condition: str

result = await agent.execute_structured(
    "北京今天的天气怎么样？",
    output_model=WeatherResult
)
print(result.city)         # "北京"
print(result.temperature)  # 23.5

6. 文件操作

# 上传文件给 agent
await agent.set_file("context.txt", "这是 agent 的上下文文件")

# 列出文件
files = await agent.list_files()

# 读取文件
content = await agent.get_file("context.txt")

7. 渠道登录 (WhatsApp/Telegram QR 码)

# 获取 QR 码
result = await client.channels.web_login_start()
qr_data_url = result["qrDataUrl"]  # base64 PNG

# 等待扫码完成
result = await client.channels.web_login_wait(timeout_ms=120000)
print(result["connected"])  # True if scanned

参考文档索引

以下是所有详细 API 参考。按需查阅：

重要约定

异常处理

from openclaw_sdk.core.exceptions import (
    OpenClawError,
    AgentNotFoundError,
    GatewayError,
    TimeoutError,
    AuthenticationError
)

try:
    result = await agent.execute("...")
except GatewayError as e:
    print(f"Gateway 连接错误: {e}")
except TimeoutError as e:
    print(f"执行超时: {e}")
except AuthenticationError as e:
    print(f"认证失败: {e}")

超时和选项

from openclaw_sdk import ExecutionOptions

options = ExecutionOptions(
    timeout_seconds=60,      # 默认 300
    stream=False,           # 是否流式
    max_tool_calls=30,      # 最多工具调用次数
    thinking=True,          # 启用思考过程
    attachments=[]           # 附件文件
)

result = await agent.execute("...", options=options)

会话管理

每个 agent 有一个 session_key，用于：

• 获取对话历史: gateway.chat_history(session_key)
• 重置记忆: agent.reset_memory()
• 中止执行: gateway.chat_abort(session_key)

Gateway 直接调用

对于 SDK 高级用户，可以直接调用 gateway RPC 方法：

# 通过 client
await client.gateway.call("sessions.list", {})

# 通过 agent
await agent.gateway.call("chat.history", {"sessionKey": agent.session_key})

流式事件类型参考

from openclaw_sdk.core.constants import EventType

# SDK 级别事件
EventType.CONTENT       # 内容块
EventType.THINKING      # 思考过程
EventType.TOOL_CALL     # 工具调用
EventType.TOOL_RESULT   # 工具结果
EventType.FILE_GENERATED # 文件生成
EventType.DONE          # 执行完成
EventType.ERROR         # 错误

# Gateway 推送事件
EventType.CHAT          # 对话事件
EventType.AGENT         # Agent 生命周期
EventType.PRESENCE      # 在线状态
EventType.HEALTH        # 健康检查
EventType.CRON          # 定时任务

调试技巧

import structlog
structlog.configure(
    wrapper_class=structlog.make_filtering_bound_logger(logging.DEBUG),
)
# 设置环境变量 OPENCLAW_LOG_LEVEL=DEBUG 查看详细日志

依赖安装

# 基础
pip install openclaw-sdk

# 可选 extras
pip install "openclaw-sdk[fastapi]"      # FastAPI 集成
pip install "openclaw-sdk[mcp]"           # MCP 支持
pip install "openclaw-sdk[dashboard]"     # Dashboard
pip install "openclaw-sdk[data-postgres]"  # PostgreSQL
pip install "openclaw-sdk[data-mysql]"    # MySQL
pip install "openclaw-sdk[alerting]"       # 告警
pip install "openclaw-sdk[all]"            # 全部依赖