@qiov/tsmai-api-openclaw 0.0.1

package/README.md

@@ -0,0 +1,306 @@
+# tsmai-api-openclaw
+
+OpenClaw 的 HTTP API 频道插件，通过 REST API 暴露 OpenClaw 上的 Agent 能力。
+
+## 功能
+
+- 通过标准 HTTP 接口调用 OpenClaw 上任意已注册的 Agent
+- 支持同步调用（`/api/chat`）和 SSE 流式调用（`/api/chat/stream`）
+- 支持多轮对话（通过 `conversationId` 维持上下文）
+- 支持指定目标 Agent 或使用默认 main Agent
+- 可选 API Key 认证
+- 跨域（CORS）支持
+
+## 目录结构
+
+```
+tsmai-api-openclaw/
+├── index.ts               # 插件入口，注册 channel
+├── package.json           # 包配置 & OpenClaw 插件声明
+├── openclaw.plugin.json   # OpenClaw 插件元数据
+├── README.md
+└── src/
+    ├── channel.ts         # ChannelPlugin 定义（配置、状态、网关启动）
+    ├── config-schema.ts   # Zod 配置 schema
+    ├── http-server.ts     # HTTP 服务核心（路由、同步/流式处理）
+    ├── onboarding.ts      # 配置向导（openclaw onboard 时交互式配置）
+    └── runtime.ts         # PluginRuntime 管理
+```
+
+## 安装
+
+```bash
+openclaw plugins install @qiov/tsmai-api-openclaw
+```
+
+安装后插件会自动注册到 `openclaw.json`，只需添加 channel 配置即可：
+
+```bash
+# 编辑 ~/.openclaw/openclaw.json，在 channels 中添加：
+#   "api": { "enabled": true, "port": 3100, "host": "0.0.0.0" }
+
+# 重启 gateway
+openclaw gateway restart
+```
+
+## 配置
+
+在 `~/.openclaw/openclaw.json` 中配置：
+
+```json
+{
+  "channels": {
+    "api": {
+      "enabled": true,
+      "port": 3100,
+      "host": "0.0.0.0",
+      "apiKey": ""
+    }
+  },
+  "plugins": {
+    "entries": {
+      "tsmai-api-openclaw": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enabled` | boolean | `true` | 是否启用 |
+| `port` | number | `3100` | HTTP 服务监听端口 |
+| `host` | string | `0.0.0.0` | HTTP 服务监听地址 |
+| `apiKey` | string | `""` | API Key（为空则不启用认证） |
+
+也支持通过环境变量配置：`API_OPENCLAW_PORT`、`API_OPENCLAW_HOST`、`API_OPENCLAW_API_KEY`。
+
+## API 接口
+
+### 健康检查
+
+```
+GET /health
+```
+
+**响应**：
+
+```json
+{ "ok": true, "status": "running" }
+```
+
+---
+
+### 同步调用
+
+```
+POST /api/chat
+Content-Type: application/json
+```
+
+等待 Agent 处理完成后返回完整回复，适用于简单快速的查询场景。
+
+**请求体**：
+
+```json
+{
+  "prompt": "分析一下最近的服务器告警",
+  "agent": "ops-lead",
+  "conversationId": "session-123"
+}
+```
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `prompt` | 是 | string | 用户提示词 |
+| `agent` | 否 | string | 目标 Agent ID，不传则使用 main agent |
+| `conversationId` | 否 | string | 会话 ID，用于多轮对话，不传自动生成 |
+
+**成功响应**：
+
+```json
+{
+  "ok": true,
+  "text": "根据分析，最近的告警主要集中在...",
+  "conversationId": "session-123"
+}
+```
+
+**错误响应**：
+
+```json
+{
+  "ok": false,
+  "error": "Missing required field: prompt"
+}
+```
+
+**curl 示例**：
+
+```bash
+# 使用默认 main agent
+curl -X POST http://localhost:3100/api/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt": "你好"}'
+
+# 指定 agent
+curl -X POST http://localhost:3100/api/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt": "分析告警", "agent": "ops-lead"}'
+
+# 多轮对话
+curl -X POST http://localhost:3100/api/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt": "继续分析", "agent": "ops-lead", "conversationId": "session-123"}'
+```
+
+---
+
+### SSE 流式调用
+
+```
+POST /api/chat/stream
+Content-Type: application/json
+```
+
+以 Server-Sent Events (SSE) 格式实时推送 Agent 处理进度，适用于复杂任务、长时间处理的场景。
+
+**请求体**：与 `/api/chat` 完全一致。
+
+**响应**：`Content-Type: text/event-stream`
+
+#### SSE 事件类型
+
+| 事件 | 触发时机 | data 字段 |
+|------|---------|----------|
+| `start` | 请求被接受，开始处理 | `{ "conversationId": "...", "agent": "..." }` |
+| `chunk` | AI 生成了一段增量文本 | `{ "text": "增量文本", "index": 0 }` |
+| `tool` | 工具/技能调用完成 | `{ "name": "tool-name", "status": "done" }` |
+| `error` | 处理出错 | `{ "error": "错误信息" }` |
+| `done` | 处理完成 | `{ "text": "完整文本", "conversationId": "..." }` |
+
+**响应示例**：
+
+```
+event: start
+data: {"conversationId":"session-123","agent":"ops-lead"}
+
+event: chunk
+data: {"text":"我是","index":0}
+
+event: chunk
+data: {"text":" IT 运维","index":1}
+
+event: chunk
+data: {"text":"团队的运维主管","index":2}
+
+event: done
+data: {"text":"我是 IT 运维团队的运维主管...","conversationId":"session-123"}
+```
+
+**curl 示例**：
+
+```bash
+curl -N -X POST http://localhost:3100/api/chat/stream \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt": "用3段话介绍你自己", "agent": "ops-lead"}'
+```
+
+**JavaScript 客户端示例**：
+
+```javascript
+async function chatStream(prompt, agent) {
+  const resp = await fetch('http://localhost:3100/api/chat/stream', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt, agent }),
+  });
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    let eventType = '';
+    for (const line of lines) {
+      if (line.startsWith('event: ')) {
+        eventType = line.slice(7);
+      } else if (line.startsWith('data: ')) {
+        const data = JSON.parse(line.slice(6));
+        switch (eventType) {
+          case 'start':
+            console.log('Started:', data.agent);
+            break;
+          case 'chunk':
+            process.stdout.write(data.text);
+            break;
+          case 'done':
+            console.log('\n\nDone. Full text:', data.text.length, 'chars');
+            break;
+          case 'error':
+            console.error('Error:', data.error);
+            break;
+        }
+      }
+    }
+  }
+}
+
+chatStream('介绍你自己', 'ops-lead');
+```
+
+---
+
+### 认证
+
+如果配置了 `apiKey`，所有 API 请求需要携带认证信息，支持两种方式：
+
+```bash
+# 方式一：X-API-Key header
+curl -H 'X-API-Key: your-api-key' ...
+
+# 方式二：Bearer token
+curl -H 'Authorization: Bearer your-api-key' ...
+```
+
+未认证请求返回：
+
+```json
+{ "ok": false, "error": "Unauthorized: invalid API key" }
+```
+
+## Agent 路由
+
+- **指定 `agent` 参数**：直接路由到对应的 Agent（需要在 `openclaw.json` 的 `agents.list` 中已注册）
+- **不指定 `agent`**：使用 `main` Agent（OpenClaw 默认 Agent）
+
+每个 Agent 可以独立配置不同的模型，例如：
+
+```json
+{
+  "agents": {
+    "list": [
+      { "id": "ops-lead", "model": "tione/kimi-k2.5" },
+      { "id": "ops-l1", "model": "minimax/MiniMax-M2.5" }
+    ]
+  }
+}
+```
+
+## 错误码
+
+| HTTP 状态码 | 说明 |
+|-------------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误（JSON 格式错误、缺少 prompt） |
+| 401 | 认证失败（API Key 无效） |
+| 404 | 路由不存在 |
+| 500 | 服务端内部错误 |

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { apiPlugin } from "./src/channel.js";
+import { setApiRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "tsmai-api-openclaw",
+  name: "HTTP API",
+  description: "HTTP API channel plugin — exposes OpenClaw agent capabilities via REST API",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setApiRuntime(api.runtime);
+    api.registerChannel({ plugin: apiPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "tsmai-api-openclaw",
+  "channels": ["api"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@qiov/tsmai-api-openclaw",
+  "version": "0.0.1",
+  "description": "HTTP API channel plugin for OpenClaw — exposes agent capabilities via REST API (sync + SSE streaming)",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "channel",
+    "http-api",
+    "sse",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {},
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "api",
+      "label": "HTTP API",
+      "selectionLabel": "HTTP API Channel",
+      "docsPath": "/channels/api",
+      "blurb": "HTTP API channel — exposes OpenClaw agent capabilities via REST API.",
+      "order": 999
+    }
+  }
+}

package/src/channel.ts

@@ -0,0 +1,212 @@
+import {
+  type ChannelPlugin,
+  type ClawdbotConfig,
+  DEFAULT_ACCOUNT_ID,
+} from "openclaw/plugin-sdk";
+import { apiOnboardingAdapter } from "./onboarding.js";
+
+export type ApiChannelConfig = {
+  enabled?: boolean;
+  port?: number;
+  host?: string;
+  apiKey?: string;
+};
+
+export type ResolvedApiAccount = {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  configured: boolean;
+  port: number;
+  host: string;
+  apiKey: string;
+};
+
+const DEFAULT_PORT = 3100;
+const DEFAULT_HOST = "0.0.0.0";
+
+function resolveCredentials(channelCfg?: ApiChannelConfig): {
+  port: number;
+  host: string;
+  apiKey: string;
+} | null {
+  const port = channelCfg?.port ?? (process.env.API_OPENCLAW_PORT ? parseInt(process.env.API_OPENCLAW_PORT, 10) : DEFAULT_PORT);
+  const host = channelCfg?.host?.trim() || process.env.API_OPENCLAW_HOST || DEFAULT_HOST;
+  const apiKey = channelCfg?.apiKey?.trim() || process.env.API_OPENCLAW_API_KEY || "";
+
+  return { port, host, apiKey };
+}
+
+function resolveAccount(cfg: ClawdbotConfig, accountId?: string): ResolvedApiAccount {
+  const channelCfg = cfg.channels?.["api"] as ApiChannelConfig | undefined;
+  const enabled = channelCfg?.enabled !== false;
+  const creds = resolveCredentials(channelCfg);
+
+  return {
+    accountId: accountId?.trim() || DEFAULT_ACCOUNT_ID,
+    name: "HTTP API",
+    enabled,
+    configured: Boolean(creds),
+    port: creds?.port ?? DEFAULT_PORT,
+    host: creds?.host ?? DEFAULT_HOST,
+    apiKey: creds?.apiKey ?? "",
+  };
+}
+
+export const apiPlugin: ChannelPlugin<ResolvedApiAccount> = {
+  id: "api",
+  meta: {
+    id: "api",
+    label: "HTTP API",
+    selectionLabel: "HTTP API Channel",
+    docsPath: "/channels/api",
+    blurb: "HTTP API channel — exposes OpenClaw agent capabilities via REST API.",
+    order: 999,
+  },
+  onboarding: apiOnboardingAdapter,
+  capabilities: {
+    chatTypes: ["direct"],
+    polls: false,
+    reactions: false,
+    threads: false,
+    media: false,
+    blockStreaming: false,
+  },
+  reload: { configPrefixes: ["channels.api"] },
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean" },
+        port: { type: "number" },
+        host: { type: "string" },
+        apiKey: { type: "string" },
+      },
+    },
+  },
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg) => resolveAccount(cfg),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, enabled }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        api: {
+          ...cfg.channels?.["api"],
+          enabled,
+        },
+      },
+    }),
+    deleteAccount: ({ cfg }) => {
+      const next = { ...cfg } as ClawdbotConfig;
+      const nextChannels = { ...cfg.channels };
+      delete (nextChannels as Record<string, unknown>)["api"];
+      if (Object.keys(nextChannels).length > 0) {
+        next.channels = nextChannels;
+      } else {
+        delete next.channels;
+      }
+      return next;
+    },
+    isConfigured: (_account, _cfg) => true, // HTTP API is always configurable
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      port: account.port,
+      host: account.host,
+    }),
+    resolveAllowFrom: () => [],
+    formatAllowFrom: ({ allowFrom }) => allowFrom,
+  },
+  setup: {
+    resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+    applyAccountConfig: ({ cfg }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        api: {
+          ...cfg.channels?.["api"],
+          enabled: true,
+        },
+      },
+    }),
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: () => [],
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      port: snapshot.port ?? null,
+      host: snapshot.host ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      lastEventAt: snapshot.lastEventAt ?? null,
+      lastInboundAt: snapshot.lastInboundAt ?? null,
+    }),
+    probeAccount: async ({ cfg }) => {
+      const account = resolveAccount(cfg);
+      const start = Date.now();
+      return {
+        ok: account.configured && account.enabled,
+        elapsedMs: Date.now() - start,
+      };
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      port: account.port,
+      host: account.host,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastEventAt: runtime?.lastEventAt ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      probe,
+    }),
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async (_ctx) => {
+      // HTTP API is request-response, outbound is handled within the request lifecycle
+      return { ok: true };
+    },
+    sendMedia: async (_ctx) => {
+      return { ok: true };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({ accountId: account.accountId, port: account.port, host: account.host, running: false });
+      ctx.log?.info(`[api] Starting HTTP API server on ${account.host}:${account.port}`);
+
+      const { startHttpServer } = await import("./http-server.js");
+      return startHttpServer({
+        port: account.port,
+        host: account.host,
+        apiKey: account.apiKey,
+        abortSignal: ctx.abortSignal,
+        log: ctx.log,
+        cfg: ctx.cfg,
+        onStatusChange: (status) => {
+          ctx.setStatus({ ...status });
+        },
+      });
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const ApiConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  port: z.number().optional(),
+  host: z.string().optional(),
+  apiKey: z.string().optional(),
+});
+
+export type ApiConfig = z.infer<typeof ApiConfigSchema>;

package/src/http-server.ts

@@ -0,0 +1,456 @@
+/**
+ * HTTP Server for the API channel plugin.
+ *
+ * Exposes two REST endpoints:
+ *
+ * 1. POST /api/chat — Synchronous (returns full reply)
+ *
+ *   Request body (JSON):
+ *     { "prompt": string, "agent": string?, "conversationId": string? }
+ *
+ *   Response body (JSON):
+ *     { "ok": true, "text": "...", "conversationId": "..." }
+ *
+ * 2. POST /api/chat/stream — SSE stream (real-time progress)
+ *
+ *   Request body: same as /api/chat
+ *
+ *   Response: text/event-stream with events:
+ *     event: start    — { conversationId, agent }
+ *     event: chunk    — { text, index }
+ *     event: tool     — { name, status }
+ *     event: error    — { error }
+ *     event: done     — { text, conversationId }
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { PluginLogger, ClawdbotConfig } from "openclaw/plugin-sdk";
+import { getApiRuntime } from "./runtime.js";
+
+export type HttpServerParams = {
+  port: number;
+  host: string;
+  apiKey?: string;
+  abortSignal?: AbortSignal;
+  log?: PluginLogger;
+  cfg?: ClawdbotConfig;
+  onStatusChange?: (status: { running: boolean; port?: number; lastEventAt?: number; lastInboundAt?: number }) => void;
+};
+
+function generateId(): string {
+  return `api-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Read the full request body as a string.
+ */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+/**
+ * Send a JSON response.
+ */
+function sendJson(res: ServerResponse, statusCode: number, body: unknown): void {
+  const data = JSON.stringify(body);
+  res.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(data),
+  });
+  res.end(data);
+}
+
+/**
+ * Strip OpenClaw internal protocol markers that may leak into plugin text.
+ */
+function stripProtocolTags(t: string): string {
+  return t.replace(/<\/?(?:final|block|tool|media)[^>]*>/gi, "").trimEnd();
+}
+
+/**
+ * Resolve agent route — shared by sync and stream endpoints.
+ */
+function resolveRoute(
+  agentId: string | undefined,
+  conversationId: string,
+  log?: PluginLogger,
+): { agentId: string; sessionKey: string; accountId: string; mainSessionKey: string } {
+  if (agentId) {
+    const normalizedAgentId = agentId.toLowerCase();
+    const normalizedConvId = conversationId.toLowerCase();
+    const sessionKey = `agent:${normalizedAgentId}:direct:${normalizedConvId}`;
+    const mainSessionKey = `agent:${normalizedAgentId}:main`;
+    log?.info(`[api] Direct agent route: agentId=${normalizedAgentId}, sessionKey=${sessionKey}`);
+    return { agentId: normalizedAgentId, sessionKey, mainSessionKey, accountId: "default" };
+  }
+  const normalizedConvId = conversationId.toLowerCase();
+  const sessionKey = `agent:main:direct:${normalizedConvId}`;
+  const mainSessionKey = "agent:main:main";
+  log?.info(`[api] Default main agent route: sessionKey=${sessionKey}`);
+  return { agentId: "main", sessionKey, mainSessionKey, accountId: "default" };
+}
+
+/**
+ * Build inbound context — shared by sync and stream endpoints.
+ */
+function buildInboundContext(
+  prompt: string,
+  route: { agentId: string; sessionKey: string; accountId: string },
+  cfg: ClawdbotConfig | undefined,
+) {
+  const runtime = getApiRuntime();
+  const envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg ?? {});
+
+  const formattedBody = runtime.channel.reply.formatInboundEnvelope({
+    channel: "API",
+    from: "api-user",
+    timestamp: Date.now(),
+    body: prompt,
+    chatType: "direct",
+    sender: { id: "api-user", name: "API User" },
+    envelope: envelopeOptions,
+  });
+
+  const messageId = generateId();
+
+  return runtime.channel.reply.finalizeInboundContext({
+    Body: formattedBody,
+    RawBody: prompt,
+    CommandBody: prompt,
+    From: "api:api-user",
+    To: "api:bot",
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: "direct",
+    SenderId: "api-user",
+    SenderName: "API User",
+    Provider: "api",
+    Surface: "api-http",
+    MessageSid: messageId,
+    MessageSidFull: messageId,
+    Timestamp: Date.now(),
+    CommandAuthorized: true,
+    OriginatingChannel: "api",
+    OriginatingTo: "api:bot",
+  });
+}
+
+/**
+ * Process user prompt through OpenClaw's agent pipeline and collect the full reply.
+ */
+async function processPrompt(
+  prompt: string,
+  agentId: string | undefined,
+  conversationId: string,
+  cfg: ClawdbotConfig | undefined,
+  log?: PluginLogger,
+): Promise<{ text: string; conversationId: string }> {
+  const runtime = getApiRuntime();
+  const route = resolveRoute(agentId, conversationId, log);
+  const messagesConfig = runtime.channel.reply.resolveEffectiveMessagesConfig(cfg ?? {}, route.agentId);
+  const ctx = buildInboundContext(prompt, route, cfg);
+
+  let fullText = "";
+
+  await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx,
+    cfg: cfg ?? {},
+    replyOptions: {
+      disableBlockStreaming: true,
+      onPartialReply: async (payload: { text?: string }) => {
+        const rawText = payload.text || "";
+        if (rawText) {
+          fullText = stripProtocolTags(rawText);
+        }
+      },
+    },
+    dispatcherOptions: {
+      responsePrefix: messagesConfig.responsePrefix,
+      deliver: async (payload: { text?: string }, info?: { kind?: string }) => {
+        const rawText = payload.text || "";
+        const kind = info?.kind;
+        const text = stripProtocolTags(rawText);
+
+        if (kind === "tool") return;
+        if (kind === "block" && text) {
+          fullText = fullText ? fullText + "\n" + text : text;
+          return;
+        }
+        if (kind === "final" || kind === undefined) {
+          if (text) fullText = text;
+        }
+      },
+      onError: (err: Error) => {
+        log?.error(`[api] Reply error: ${err.message}`);
+      },
+    },
+  });
+
+  return { text: fullText, conversationId };
+}
+
+/**
+ * Send a single SSE event to the response stream.
+ */
+function sendSSE(res: ServerResponse, event: string, data: unknown): void {
+  res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+
+/**
+ * Process user prompt with SSE streaming — pushes events in real-time.
+ */
+async function processPromptStream(
+  res: ServerResponse,
+  prompt: string,
+  agentId: string | undefined,
+  conversationId: string,
+  cfg: ClawdbotConfig | undefined,
+  log?: PluginLogger,
+): Promise<void> {
+  const runtime = getApiRuntime();
+  const route = resolveRoute(agentId, conversationId, log);
+  const messagesConfig = runtime.channel.reply.resolveEffectiveMessagesConfig(cfg ?? {}, route.agentId);
+  const ctx = buildInboundContext(prompt, route, cfg);
+
+  // Send start event
+  sendSSE(res, "start", { conversationId, agent: route.agentId });
+
+  let chunkIndex = 0;
+  let fullText = "";
+  let streamedCleanText = "";
+
+  await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx,
+    cfg: cfg ?? {},
+    replyOptions: {
+      disableBlockStreaming: false, // Enable streaming for SSE
+      onPartialReply: async (payload: { text?: string }) => {
+        const rawText = payload.text || "";
+        if (!rawText) return;
+
+        const cleanText = stripProtocolTags(rawText);
+        if (!cleanText) return;
+
+        // Compute delta (incremental text)
+        let delta = cleanText;
+        if (cleanText.startsWith(streamedCleanText)) {
+          delta = cleanText.slice(streamedCleanText.length);
+        }
+        if (!delta) return;
+
+        streamedCleanText = cleanText;
+        fullText = cleanText;
+
+        sendSSE(res, "chunk", { text: delta, index: chunkIndex });
+        chunkIndex++;
+      },
+    },
+    dispatcherOptions: {
+      responsePrefix: messagesConfig.responsePrefix,
+      deliver: async (payload: { text?: string }, info?: { kind?: string }) => {
+        const rawText = payload.text || "";
+        const kind = info?.kind;
+        const text = stripProtocolTags(rawText);
+
+        if (kind === "tool") {
+          // Extract tool name from payload if available
+          const toolName = (payload as any).toolName || (payload as any).name || "tool";
+          sendSSE(res, "tool", { name: toolName, status: "done" });
+          return;
+        }
+
+        if (kind === "block" && text) {
+          // Skip if already streamed via onPartialReply
+          if (streamedCleanText && streamedCleanText.includes(text.trim())) return;
+
+          sendSSE(res, "chunk", { text, index: chunkIndex });
+          chunkIndex++;
+          fullText = fullText ? fullText + "\n" + text : text;
+          streamedCleanText = fullText;
+          return;
+        }
+
+        if (kind === "final" || kind === undefined) {
+          if (text) fullText = text;
+        }
+      },
+      onError: (err: Error) => {
+        log?.error(`[api/stream] Reply error: ${err.message}`);
+        sendSSE(res, "error", { error: err.message });
+      },
+    },
+  });
+
+  // Send done event with full text
+  const finalText = fullText || streamedCleanText;
+  sendSSE(res, "done", { text: finalText, conversationId });
+}
+
+/**
+ * Start the HTTP server for the API channel.
+ */
+export async function startHttpServer(params: HttpServerParams): Promise<void> {
+  const { port, host, apiKey, abortSignal, log, cfg, onStatusChange } = params;
+
+  return new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+      // CORS headers
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Key");
+
+      // Handle preflight
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // Health check
+      if (req.method === "GET" && req.url === "/health") {
+        sendJson(res, 200, { ok: true, status: "running" });
+        return;
+      }
+
+      // Route: POST /api/chat/stream (SSE) — must check before /api/chat
+      if (req.method === "POST" && req.url?.startsWith("/api/chat/stream")) {
+        // API key auth
+        if (apiKey) {
+          const reqKey =
+            req.headers["x-api-key"] as string ||
+            req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+          if (reqKey !== apiKey) {
+            sendJson(res, 401, { ok: false, error: "Unauthorized: invalid API key" });
+            return;
+          }
+        }
+
+        try {
+          const body = await readBody(req);
+          let parsed: { prompt?: string; agent?: string; conversationId?: string };
+
+          try {
+            parsed = JSON.parse(body);
+          } catch {
+            sendJson(res, 400, { ok: false, error: "Invalid JSON body" });
+            return;
+          }
+
+          const prompt = parsed.prompt?.trim();
+          if (!prompt) {
+            sendJson(res, 400, { ok: false, error: "Missing required field: prompt" });
+            return;
+          }
+
+          const agentId = parsed.agent?.trim() || undefined;
+          const conversationId = parsed.conversationId?.trim() || generateId();
+
+          log?.info(`[api/stream] Received request: prompt="${prompt.slice(0, 80)}...", agent=${agentId || "default"}`);
+          onStatusChange?.({ running: true, port, lastEventAt: Date.now(), lastInboundAt: Date.now() });
+
+          // Set SSE headers
+          res.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "Access-Control-Allow-Origin": "*",
+          });
+
+          await processPromptStream(res, prompt, agentId, conversationId, cfg, log);
+        } catch (err) {
+          log?.error(`[api/stream] Request processing error: ${err}`);
+          // If headers already sent, push error event; otherwise send JSON error
+          if (res.headersSent) {
+            sendSSE(res, "error", { error: `Internal error: ${(err as Error).message}` });
+          } else {
+            sendJson(res, 500, { ok: false, error: `Internal error: ${(err as Error).message}` });
+          }
+        } finally {
+          if (!res.writableEnded) res.end();
+        }
+        return;
+      }
+
+      // Route: POST /api/chat (sync)
+      if (req.method !== "POST" || !req.url?.startsWith("/api/chat")) {
+        sendJson(res, 404, { ok: false, error: "Not found. Use POST /api/chat or /api/chat/stream" });
+        return;
+      }
+
+      // API key auth (if configured)
+      if (apiKey) {
+        const reqKey =
+          req.headers["x-api-key"] as string ||
+          req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+        if (reqKey !== apiKey) {
+          sendJson(res, 401, { ok: false, error: "Unauthorized: invalid API key" });
+          return;
+        }
+      }
+
+      try {
+        const body = await readBody(req);
+        let parsed: { prompt?: string; agent?: string; conversationId?: string };
+
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          sendJson(res, 400, { ok: false, error: "Invalid JSON body" });
+          return;
+        }
+
+        const prompt = parsed.prompt?.trim();
+        if (!prompt) {
+          sendJson(res, 400, { ok: false, error: "Missing required field: prompt" });
+          return;
+        }
+
+        const agentId = parsed.agent?.trim() || undefined;
+        const conversationId = parsed.conversationId?.trim() || generateId();
+
+        log?.info(`[api] Received request: prompt="${prompt.slice(0, 80)}...", agent=${agentId || "default"}`);
+        onStatusChange?.({ running: true, port, lastEventAt: Date.now(), lastInboundAt: Date.now() });
+
+        const result = await processPrompt(prompt, agentId, conversationId, cfg, log);
+
+        sendJson(res, 200, {
+          ok: true,
+          text: result.text,
+          conversationId: result.conversationId,
+        });
+      } catch (err) {
+        log?.error(`[api] Request processing error: ${err}`);
+        sendJson(res, 500, {
+          ok: false,
+          error: `Internal error: ${(err as Error).message}`,
+        });
+      }
+    });
+
+    // Handle abort signal
+    if (abortSignal) {
+      const abortHandler = () => {
+        server.close();
+        onStatusChange?.({ running: false });
+        resolve();
+      };
+      abortSignal.addEventListener("abort", abortHandler);
+    }
+
+    server.on("error", (err) => {
+      log?.error(`[api] HTTP server error: ${err}`);
+      onStatusChange?.({ running: false });
+      reject(err);
+    });
+
+    server.listen(port, host, () => {
+      log?.info(`[api] HTTP server listening on http://${host}:${port}`);
+      onStatusChange?.({ running: true, port, lastEventAt: Date.now() });
+    });
+  });
+}

package/src/onboarding.ts

@@ -0,0 +1,138 @@
+import type {
+  ChannelOnboardingAdapter,
+  OpenClawConfig,
+  WizardPrompter,
+} from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+
+const channel = "api" as const;
+
+type ApiChannelConfig = {
+  enabled?: boolean;
+  port?: number;
+  host?: string;
+  apiKey?: string;
+};
+
+function getChannelConfig(cfg: OpenClawConfig): ApiChannelConfig | undefined {
+  return cfg.channels?.["api"] as ApiChannelConfig | undefined;
+}
+
+function isConfigured(channelCfg?: ApiChannelConfig): boolean {
+  // API channel is always "configured" as long as it has a port
+  const port = channelCfg?.port ?? (process.env.API_OPENCLAW_PORT ? parseInt(process.env.API_OPENCLAW_PORT, 10) : 3100);
+  return Boolean(port);
+}
+
+function updateConfig(
+  cfg: OpenClawConfig,
+  updates: { port?: number; host?: string; apiKey?: string; enabled?: boolean },
+): OpenClawConfig {
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      api: {
+        ...cfg.channels?.["api"],
+        ...updates,
+        enabled: updates.enabled ?? true,
+      },
+    },
+  };
+}
+
+async function noteSetup(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "HTTP API channel exposes OpenClaw agent capabilities via a REST endpoint.",
+      "You can configure the port, host, and an optional API key for authentication.",
+      "",
+      "Once running, send POST requests to /api/chat with:",
+      '  { "prompt": "your question", "agent": "optional-agent-id" }',
+    ].join("\n"),
+    "HTTP API setup",
+  );
+}
+
+export const apiOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const channelCfg = getChannelConfig(cfg);
+    const configured = isConfigured(channelCfg);
+
+    return {
+      channel,
+      configured,
+      statusLines: [`HTTP API: ${configured ? "configured" : "needs configuration"}`],
+      selectionHint: configured ? "configured" : "requires configuration",
+      quickstartScore: configured ? 1 : 10,
+    };
+  },
+  configure: async ({ cfg, prompter }) => {
+    let next = cfg;
+    const accountId = DEFAULT_ACCOUNT_ID;
+
+    await noteSetup(prompter);
+
+    const channelCfg = getChannelConfig(next);
+
+    // Check for env vars
+    const envPort = process.env.API_OPENCLAW_PORT ? parseInt(process.env.API_OPENCLAW_PORT, 10) : undefined;
+    const envHost = process.env.API_OPENCLAW_HOST?.trim();
+    const envApiKey = process.env.API_OPENCLAW_API_KEY?.trim();
+
+    if (envPort) {
+      const useEnv = await prompter.confirm({
+        message: `API_OPENCLAW_PORT=${envPort} detected in env. Use environment variables?`,
+        initialValue: true,
+      });
+      if (useEnv) {
+        next = updateConfig(next, { enabled: true });
+        return { cfg: next, accountId };
+      }
+    }
+
+    // Prompt for port
+    const portInput = await prompter.text({
+      message: "HTTP server port",
+      placeholder: "3100",
+      initialValue: channelCfg?.port?.toString() || envPort?.toString() || "3100",
+      validate: (value) => {
+        const n = parseInt(String(value), 10);
+        return Number.isInteger(n) && n > 0 && n < 65536 ? undefined : "Must be a valid port (1-65535)";
+      },
+    });
+    const port = parseInt(String(portInput), 10);
+
+    // Prompt for host
+    const hostInput = await prompter.text({
+      message: "HTTP server host",
+      placeholder: "0.0.0.0",
+      initialValue: channelCfg?.host?.trim() || envHost || "0.0.0.0",
+    });
+    const host = String(hostInput).trim() || "0.0.0.0";
+
+    // Prompt for API key (optional)
+    const apiKeyInput = await prompter.text({
+      message: "API Key (optional, leave empty for no authentication)",
+      placeholder: "",
+      initialValue: channelCfg?.apiKey?.trim() || envApiKey || "",
+    });
+    const apiKey = String(apiKeyInput).trim();
+
+    next = updateConfig(next, { port, host, apiKey, enabled: true });
+    return { cfg: next, accountId };
+  },
+  disable: (cfg) => {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        api: {
+          ...cfg.channels?.["api"],
+          enabled: false,
+        },
+      },
+    };
+  },
+};

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let apiRuntime: PluginRuntime | null = null;
+
+export function setApiRuntime(runtime: PluginRuntime): void {
+  apiRuntime = runtime;
+}
+
+export function getApiRuntime(): PluginRuntime {
+  if (!apiRuntime) {
+    throw new Error("API runtime not initialized");
+  }
+  return apiRuntime;
+}