基于 OpenClaw 开发

OpenClaw（原名 Clawdbot/Moltbot）是一个免费、开源的自主 AI 助手，可以在用户自己的设备上运行，通过消息应用与用户交互，执行各种自动化任务。云开发提供了 @cloudbase/agent-adapter-llm 适配器，让 OpenClaw Agent 可以通过 OpenAI 兼容接口无缝对接 AG-UI 协议。

前置条件

Node.js 20+
已开通云开发环境
已拥有运行中的 Linux 服务器（用于部署 OpenClaw 服务）
已获取 OpenClaw 配置信息（Gateway Token、Base URL、Agent ID）

安装依赖

npm install @cloudbase/agent-adapter-llm @cloudbase/agent-server openai express

快速开始

1. 准备 OpenClaw 服务器

在创建 OpenClaw Agent 前，需要先准备一台运行 OpenClaw 服务的服务器，如果没有现成的服务器，可以使用云开发的轻量应用服务器模块快速创建。

使用云开发轻量应用服务器

登录云开发控制台，选择进入轻量应用服务器页面
创建一个新的服务器实例，选择 OpenClaw 应用镜像

在实例创建成功后，进入实例详情页，在防火墙标签页中，添加规则：来源全部 IPv4 地址，端口 7070，协议 TCP，策略允许

配置 OpenClaw 使用的模型

首先，你需要为 OpenClaw 配置模型，如果你已经配置过，可以跳过这一步。你可以通过轻量应用服务器控制台，或参照 OpenClaw Onboarding 指引快速开始。

在使用轻量应用服务器控制台的情况下，进入「应用管理」标签页，即可快速配置模型。

自定义模型 JSON 配置示例：

{
  "provider": "cloudbase",
  "base_url": "https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/<PROVIDER>",
  "api": "openai-completions",
  "api_key": "your-api-key-here",
  "model": {
    "id": "deepseek-v4-flash",
    "name": "Hunyuan TurboS Latest"
  }
}

提示

云开发提供了统一的大模型 HTTP 端点，支持腾讯混元和 DeepSeek 等模型。端点格式为：

https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/<PROVIDER>

其中 ENV_ID 为你的云开发环境 ID，PROVIDER 可选 cloudbase，详见接入大模型。

获取 OpenClaw 配置信息并放通 OpenAI 接口

通过 SSH 连接到服务器后，执行以下命令下载并运行配置脚本：

curl -fsSL https://tcb.cloud.tencent.com/ai/agent/templates/openclaw_setup.sh | bash

脚本执行完成后，会输出 OpenClaw 的配置信息，请记录以下内容用于后续环境变量配置：

┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw 配置信息                        │
├─────────────────────────────────────────────────────────────┤
│ Gateway Token       : <你的 Gateway Token>                  │
│ Agent ID            : main                                  │
│ OpenAI BaseURL      : http://<公网IP>:7070                  │
└─────────────────────────────────────────────────────────────┘

2. 创建 OpenClaw Agent

// index.ts
import express from "express";
import { createExpressRoutes } from "@cloudbase/agent-server";
import { LLMAgent } from "@cloudbase/agent-adapter-llm";
import OpenAI from "openai";

function createAgent({ request }: { request: Request }) {
  const agent = new LLMAgent({
    model: new OpenAI({
      apiKey: process.env.OPENCLAW_GATEWAY_TOKEN || "",
      baseURL: process.env.OPENCLAW_BASE_URL || "",
    }),
    modelName: `openclaw:${process.env.OPENCLAW_AGENT_ID || "main"}`,
  });
  return { agent };
}

const app = express();

createExpressRoutes({
  createAgent,
  express: app,
});

app.listen(9000, () => console.log("Listening on 9000!"));

3. 配置环境变量

创建 .env 文件，将安装脚本输出的配置信息填入对应的环境变量：

# OpenClaw Gateway Token（对应脚本输出的 "Gateway Token"）
OPENCLAW_GATEWAY_TOKEN=your_gateway_token_here

# OpenClaw API 基础 URL（对应脚本输出的 "OpenAI BaseURL"）
OPENCLAW_BASE_URL=http://<公网IP>:7070

# OpenClaw Agent ID（对应脚本输出的 "Agent ID"，默认为 main）
OPENCLAW_AGENT_ID=main

4. 启动服务

npx tsx src/index.ts

服务将在 http://localhost:9000 启动，自动创建以下路由：

POST /send-message - AG-UI 协议的消息发送接口
POST /chat/completions - OpenAI 兼容的聊天接口

核心 API

LLMAgent

将 OpenClaw 包装为 AG-UI 兼容的 Agent：

import { LLMAgent } from "@cloudbase/agent-adapter-llm";
import OpenAI from "openai";

const agent = new LLMAgent({
  model: new OpenAI({
    apiKey: process.env.OPENCLAW_GATEWAY_TOKEN,
    baseURL: process.env.OPENCLAW_BASE_URL,
  }),
  modelName: `openclaw:${process.env.OPENCLAW_AGENT_ID}`,
});

构造参数：

参数	类型	说明
`model`	`OpenAI`	OpenAI SDK 实例，配置 OpenClaw 的 API 密钥和基础 URL
`modelName`	`string`	模型名称，格式为 `openclaw:<agent_id>`

Middleware

使用中间件机制扩展 Agent 功能：

agent.use(middleware);

高级用法

用户认证中间件

通过 AG-UI 的 Middleware 机制，可以在 Agent 处理请求前注入用户信息：

import {
  Middleware,
  RunAgentInput,
  BaseEvent,
  AbstractAgent,
} from "@ag-ui/client";
import { jwtDecode, JwtPayload } from "jwt-decode";
import { Observable } from "rxjs";

export class DetectCloudbaseUserMiddleware extends Middleware {
  _req: Request;
  constructor(req: Request) {
    super();
    this._req = req;
  }
  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    let jwtToken: JwtPayload = {};
    try {
      const user =
        (this._req.headers as any).Authorization ||
        this._req.headers.get?.("Authorization");
      if (user) {
        const jwt = user.split(" ")[1];
        if (!jwt) throw new Error("invalid jwt");
        const decoded = jwtDecode(jwt);
        if (!decoded || !decoded.sub) throw new Error("invalid jwt");
        jwtToken = decoded;
      }
    } catch (e) {
      // 忽略错误，继续处理请求
    }
    if (jwtToken?.sub) {
      return next.run({
        ...input,
        state: {
          ...input.state,
          __request_context__: {
            user: { id: jwtToken.sub, jwt: jwtToken },
            request: this._req,
          },
        },
      });
    } else {
      return next.run(input);
    }
  }
}

使用中间件：

function createAgent({ request }: { request: Request }) {
  const agent = new LLMAgent({
    model: new OpenAI({
      apiKey: process.env.OPENCLAW_GATEWAY_TOKEN || "",
      baseURL: process.env.OPENCLAW_BASE_URL || "",
    }),
    modelName: `openclaw:${process.env.OPENCLAW_AGENT_ID || "main"}`,
  });
  // 使用中间件从 JWT 提取用户信息
  agent.use(new DetectCloudbaseUserMiddleware(request));
  return { agent };
}

DetectCloudbaseUserMiddleware 中间件会自动从 HTTP 请求的 Authorization header 中提取 JWT Token，解析出用户 ID（sub 字段），并将其注入到 input.state.__request_context__ 中。

流式输出

LLMAgent 默认支持流式输出，无需额外配置。客户端会收到流式的 TEXT_MESSAGE_CONTENT 事件。

本地调试

使用 cURL 测试

# 发送消息（流式响应）
curl -X POST http://localhost:9000/send-message \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "threadId": "test-thread-123",
    "runId": "test-run-001",
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "你好，请介绍一下自己"
      }
    ],
    "tools": [],
    "context": [],
    "state": {},
    "forwardedProps": {}
  }'

带用户认证的请求

curl -X POST http://localhost:9000/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: text/event-stream" \
  -d '{
    "threadId": "test-thread-123",
    "runId": "test-run-002",
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "你好"
      }
    ],
    "tools": [],
    "context": [],
    "state": {},
    "forwardedProps": {}
  }'

使用 OpenAI 兼容接口

curl -X POST http://localhost:9000/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw:main",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ],
    "stream": true
  }'

部署

云函数部署

参考 HTTP 云函数部署

云托管部署

参考云托管部署

Dockerfile 示例：

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY . .
RUN npm run build

ENV PORT=9000
EXPOSE 9000

CMD ["node", "dist/index.js"]

项目结构

openclaw-ts/
├── src/
│   ├── index.ts              # 主入口文件
│   └── utils.ts              # 工具函数和中间件
├── dist/                     # 编译输出目录
├── .env.example              # 环境变量示例
├── package.json              # 项目配置
├── tsconfig.json             # TypeScript 配置
├── scf_bootstrap             # 云函数启动脚本
├── Dockerfile                # Docker 镜像配置
└── README.md                 # 项目说明

最佳实践

1. 使用环境变量

const agent = new LLMAgent({
  model: new OpenAI({
    apiKey: process.env.OPENCLAW_GATEWAY_TOKEN || "",
    baseURL: process.env.OPENCLAW_BASE_URL || "",
  }),
  modelName: `openclaw:${process.env.OPENCLAW_AGENT_ID || "main"}`,
});

2. 错误处理

在中间件中妥善处理错误，避免因认证失败导致请求中断：

try {
  // 解析 JWT
} catch (e) {
  // 忽略错误，继续处理请求
}

3. CORS 配置

如遇跨域问题，可启用 CORS 中间件：

import cors from "cors";

app.use(
  cors({
    origin: true,
  }),
);

前置条件​

安装依赖​

快速开始​

1. 准备 OpenClaw 服务器​

使用云开发轻量应用服务器​

配置 OpenClaw 使用的模型​

获取 OpenClaw 配置信息并放通 OpenAI 接口​

2. 创建 OpenClaw Agent​

3. 配置环境变量​

4. 启动服务​

核心 API​

LLMAgent​

Middleware​

高级用法​

用户认证中间件​

流式输出​

本地调试​

使用 cURL 测试​

带用户认证的请求​

使用 OpenAI 兼容接口​

部署​

云函数部署​

云托管部署​

项目结构​

最佳实践​

1. 使用环境变量​

2. 错误处理​

3. CORS 配置​

相关文档​