第 18 章 · 构建商业产品

当你的 OpenClaw Agent 从"自己用得好"到"别人愿意付费用"，你就站在了产品化的起点上。

本章你将学到：

• 理解 OpenClaw 提供的三种 HTTP API 及其适用场景
• 掌握 Control UI、TUI、WebChat 三种交互界面的部署方式
• 学会用量追踪和成本监控来控制运营成本
• 设计基于 OpenClaw 的多租户 SaaS 架构

18.1 产品化路径：从个人助手到商业产品

OpenClaw 不只是一个"自用 AI 助手框架"——它内置了多种 API 暴露方式、用户管理界面、用量追踪和成本控制，这些都是构建商业产品的基础设施。

产品化成熟度模型：

Level 1：个人助手
  └─ 单用户、单 Gateway、CLI/TUI 交互
  └─ 价值：提升个人效率

Level 2：团队工具
  └─ 多用户、DM 隔离、Control UI 管理
  └─ 价值：团队共享 AI 能力

Level 3：API 平台
  └─ OpenAI 兼容 API、Tools Invoke API
  └─ 价值：集成到现有工作流

Level 4：SaaS 产品
  └─ 多 Gateway、多租户、白标定制
  └─ 价值：可规模化收入

本章从 Level 3 和 Level 4 的视角出发，讲解 OpenClaw 的产品化能力。

18.2 OpenAI 兼容 HTTP API

这是 OpenClaw 产品化最有价值的特性之一：把 Agent 暴露为标准 OpenAI API。

18.2.1 为什么这很重要

市面上有大量工具期望接入 OpenAI 的 /v1/chat/completions 端点——Open WebUI、LobeChat、LibreChat、各种 RAG 系统、Cursor、Continue……如果你能把 OpenClaw 的 Agent 暴露为 OpenAI 兼容 API，这些工具就能直接接入，零适配成本。

┌─────────────────────────────────────────────────────┐
│              OpenAI 兼容 API                         │
│                                                     │
│  POST /v1/chat/completions   ← 大多数客户端         │
│  POST /v1/responses          ← Agent 原生客户端     │
│  GET  /v1/models             ← 模型/Agent 列表      │
│  POST /v1/embeddings         ← RAG 系统             │
│                                                     │
│  全部在同一个端口上（WS + HTTP 多路复用）              │
│  默认端口：18789                                      │
└─────────────────────────────────────────────────────┘

18.2.2 启用 API

默认关闭，需要在配置中启用：

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
        responses: { enabled: true },
      },
    },
  },
}

18.2.3 Agent-First 模型契约

OpenClaw 的 /v1/chat/completions 不是简单地转发请求到模型——它把 OpenAI 的 model 字段解释为 Agent 目标，而不是原始模型 ID：

model: "openclaw"           → 路由到默认 Agent
model: "openclaw/default"  → 路由到默认 Agent（稳定别名）
model: "openclaw/research"  → 路由到 ID 为 "research" 的 Agent

// 通过 Header 覆盖后端模型
x-openclaw-model: openai/gpt-5.4
x-openclaw-session-key: my-session
x-openclaw-message-channel: slack

这意味着 /v1/models 返回的是 Agent 目标列表，而不是原始 Provider 的模型目录。这种设计让 OpenAI 兼容客户端可以透明地使用 OpenClaw 的多 Agent 路由。

18.2.4 会话行为

默认情况下，API 是无状态的——每次请求生成新的会话密钥。

如果你在请求中包含 OpenAI 的 user 字段，Gateway 会从中推导出一个稳定的会话密钥，这样多次调用可以共享同一个 Agent 会话：

{
  "model": "openclaw/default",
  "user": "alice",
  "messages": [{"role": "user", "content": "你好"}]
}

后续请求只要 user 相同，就会继续之前的对话。

18.2.5 流式输出

设置 stream: true 接收 SSE 事件：

curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "stream": true,
    "messages": [{"role":"user","content":"你好"}]
  }'

返回格式：

data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
...
data: [DONE]

18.2.6 Open WebUI 接入示例

最常见的用法是把 OpenClaw 接入 Open WebUI：

# 1. 启用 API（配置如上）
# 2. 重启 Gateway

# 3. 在 Open WebUI 中配置：
#    Base URL: http://127.0.0.1:18789/v1
#    API Key: 你的 Gateway Token
#    Model: openclaw/default

# 4. 验证连通性
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'
# 应返回 openclaw/default

⚠️ 安全警告

/v1/chat/completions 端点是一个完整的管理员访问面。通过 Gateway 认证的调用者被视为该 Gateway 实例的受信任操作者。没有单独的"每用户工具边界"。

务必只在 loopback/Tailnet/私有网络内暴露此端点，不要直接暴露到公网。

18.2.7 Embeddings 端点

/v1/embeddings 使用同样的 Agent 目标模型契约：

curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'

18.3 OpenResponses API

/v1/responses 是 OpenClaw 对 OpenAI Responses API 的兼容实现。相比 Chat Completions，它支持更丰富的输入类型——基于 Item 的输入、客户端工具调用、图片和文件上传。

18.3.1 启用

{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: true },
      },
    },
  },
}

18.3.2 请求格式

{
  "model": "openclaw",
  "input": "你好",
  "instructions": "你是一个专业的技术助手",
  "stream": false
}

input 可以是字符串，也可以是 Item 数组：

{
  "model": "openclaw",
  "input": [
    { "type": "message", "role": "user", "content": "分析这张图" },
    { "type": "input_image", "source": { "type": "url", "url": "https://example.com/photo.png" } }
  ]
}

18.3.3 客户端工具调用

你可以通过 tools 参数定义客户端侧的函数工具：

{
  "model": "openclaw",
  "input": "查一下天气",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          }
        }
      }
    }
  ]
}

Agent 决定调用工具时，响应中会返回 function_call 类型的输出项。你再用 function_call_output 把结果送回去。

18.3.4 文件和图片上传

支持 Base64 和 URL 两种来源：

{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

支持的文件类型：text/plain、text/markdown、text/html、text/csv、application/json、application/pdf（最大 5MB）

支持的图片类型：image/jpeg、image/png、image/gif、image/webp、image/heic、image/heif（最大 10MB）

PDF 会被自动解析——如果文字内容很少，前几页会被光栅化为图片传给模型。

18.3.5 安全配置

可以通过配置限制 URL 来源、文件大小等：

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxUrlParts: 8,
          files: {
            allowUrl: true,
            urlAllowlist: ["cdn.example.com"],
            maxBytes: 5242880,
            pdf: { maxPages: 4 },
          },
          images: {
            allowUrl: true,
            urlAllowlist: ["images.example.com"],
            maxBytes: 10485760,
          },
        },
      },
    },
  },
}

URL 允许列表在获取前和重定向时都会强制执行。但即使允许了某个主机名，也不会绕过私有 IP 阻止。

18.4 Tools Invoke API

有时候你不需要完整的 Agent 对话——只需要调用一个特定的工具。/tools/invoke 端点就是为此设计的。

18.4.1 端点

• POST /tools/invoke
• 默认启用（不需要额外配置）

18.4.2 请求格式

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main"
}

18.4.3 策略过滤

工具可用性经过与 Gateway Agent 相同的策略链过滤：

工具策略链：
1. tools.profile / tools.byProvider.profile
2. tools.allow / tools.byProvider.allow
3. agents.<id>.tools.allow
4. 群组策略（如果会话映射到群组或通道）
5. 子 Agent 策略（如果用子 Agent 会话调用）

如果工具不被策略允许，端点返回 404。

18.4.4 硬拒绝列表

Gateway HTTP 默认硬拒绝以下工具（即使会话策略允许）：

cron                 ← 防止创建定时任务
sessions_spawn       ← 防止派生子 Agent
sessions_send        ← 防止跨会话发送
gateway              ← 防止操作 Gateway 本身
whatsapp_login       ← 防止 WhatsApp 登录

你可以自定义拒绝列表：

{
  gateway: {
    tools: {
      deny: ["browser"],     // 额外阻止浏览器工具
      allow: ["gateway"],    // 从默认拒绝中移除
    },
  },
}

18.4.5 响应

// 成功
{ "ok": true, "result": { ... } }

// 工具不允许
// HTTP 404

// 请求无效
{ "ok": false, "error": { "type": "...", "message": "..." } }

18.5 Control UI：浏览器管理界面

Control UI 是 OpenClaw 内置的 Web 管理界面——一个基于 Vite + Lit 构建的单页应用。

18.5.1 访问方式

本地访问：
  http://127.0.0.1:18789/

远程访问（推荐 Tailscale）：
  https://<magicdns>/

自定义路径：
  gateway.controlUi.basePath: "/openclaw"
  → http://127.0.0.1:18789/openclaw/

18.5.2 认证

Control UI 通过 WebSocket 握手时的 connect.params.auth 进行认证：

• token 模式：使用 gateway.auth.token
• password 模式：使用 gateway.auth.password
• Tailscale 模式：当 gateway.auth.allowTailscale: true 时，通过 Tailscale 身份头认证

快速打开：

# 自动打开浏览器
openclaw dashboard

18.5.3 设备配对

从新浏览器或设备连接时，Gateway 要求一次性配对审批：

# 查看待审批请求
openclaw devices list

# 审批
openclaw devices approve <requestId>

本地连接（127.0.0.1）自动批准，远程连接需要显式审批。

18.5.4 功能全景

Control UI 提供了 Gateway 的完整管理能力：

┌─────────────────────────────────────────────────────┐
│                  Control UI 功能                     │
├─────────────────────────────────────────────────────┤
│                                                     │
│  聊天                                              │
│  ├─ 实时流式对话                                    │
│  ├─ 工具调用卡片 + 实时输出                         │
│  └─ 中止运行（Stop 按钮 + /stop 命令）               │
│                                                     │
│  通道管理                                          │
│  ├─ WhatsApp/Telegram/Discord/Slack 状态            │
│  ├─ QR 码登录                                      │
│  └─ 每通道配置编辑                                  │
│                                                     │
│  会话管理                                          │
│  ├─ 会话列表 + per-session 覆盖                      │
│  ├─ thinking/fast/verbose/reasoning 切换            │
│  └─ 模型选择器                                      │
│                                                     │
│  Cron 任务                                         │
│  ├─ 创建/编辑/运行/启用/禁用                         │
│  ├─ 运行历史                                        │
│  └─ Webhook 投递                                    │
│                                                     │
│  技能管理                                          │
│  ├─ 状态查看 + 启用/禁用                             │
│  └─ 安装 + API Key 更新                              │
│                                                     │
│  配置管理                                          │
│  ├─ 查看/编辑 openclaw.json                         │
│  ├─ Schema 表单 + Raw JSON 编辑器                    │
│  └─ 验证 + 应用 + 重启                              │
│                                                     │
│  调试                                              │
│  ├─ 状态/健康/模型快照                               │
│  ├─ 事件日志                                        │
│  └─ 手动 RPC 调用                                   │
│                                                     │
│  其他                                              │
│  ├─ 节点列表 + 能力                                  │
│  ├─ Exec 审批列表                                    │
│  ├─ 日志实时跟踪                                     │
│  └─ 版本更新                                        │
│                                                     │
└─────────────────────────────────────────────────────┘

18.5.5 多语言支持

Control UI 支持根据浏览器语言自动本地化：

支持的语言：
  en（英语）、zh-CN（简体中文）、zh-TW（繁体中文）、
  pt-BR（巴西葡萄牙语）、de（德语）、es（西班牙语）

非英语翻译在浏览器中按需加载。缺失的翻译键回退到英语。

18.6 TUI 和 WebChat

除了浏览器管理界面，OpenClaw 还提供终端 UI 和原生聊天 UI。

18.6.1 TUI（Terminal UI）

TUI 是一个终端内的完整聊天界面，适合 SSH 远程使用：

# 本地
openclaw tui

# 远程
openclaw tui --url ws://<host>:<port> --token <gateway-token>

核心功能：

• 实时流式对话
• 工具调用卡片（Ctrl+O 展开/折叠）
• 模型选择器（Ctrl+L）
• Agent 选择器（Ctrl+G）
• 会话选择器（Ctrl+P）
• 本地 Shell 命令（! 前缀）
• 快捷键：Enter 发送、Esc 中止、Ctrl+C 清空输入

会话模型：

• 会话键存储为 agent:<agentId>:<sessionKey>
• /session main 展开为 agent:<currentAgent>:main
• 支持 per-sender（默认）和 global 作用域

18.6.2 WebChat

WebChat 是原生聊天 UI（macOS/iOS SwiftUI），直接通过 Gateway WebSocket 通信：

• 使用相同的会话和路由规则
• 确定性路由：回复始终回到 WebChat
• 历史记录始终从 Gateway 获取（无本地文件监听）
• Gateway 不可达时只读
• 中止的运行保留部分输出

18.6.3 投递控制

默认情况下，TUI 发送的消息不会投递到通道。要启用：

# 在 TUI 中
/deliver on

# 或启动时
openclaw tui --deliver

18.7 用量追踪与成本监控

18.7.1 用量追踪的来源

OpenClaw 的用量追踪不估算成本——它直接从 Provider 的用量端点拉取真实数据：

支持的 Provider 和认证方式：

Provider              认证方式
──────────────────────────────────
Anthropic (Claude)     OAuth Token
GitHub Copilot         OAuth Token
Gemini CLI             OAuth Token
OpenAI Codex           OAuth Token
MiniMax                API Key
z.ai                   API Key

没有匹配的 OAuth/API 凭据时，用量信息会自动隐藏。

18.7.2 用量展示位置

位置	展示内容
/status	会话 Token + 估算成本（仅 API Key）+ 当前模型 Provider 用量
/usage tokens	每次回复的 Token 用量
/usage cost	从会话日志聚合的本地成本摘要
openclaw status --usage	完整的每 Provider 用量明细
openclaw channels list	Provider 用量快照
macOS 菜单栏	"Usage" 区域（如果可用）

18.7.3 成本控制策略

成本控制三板斧：

1. 模型选择
   ├─ 日常对话用 Sonnet（便宜 10 倍）
   ├─ 复杂推理用 Opus（只在不降级时用）
   └─ 设置 fallbacks 确保主模型不可用时有备选

2. 上下文管理
   ├─ 定期 /new 重置会话（释放上下文 = 释放 Token）
   ├─ 启用剪裁（contextPruning）减少旧工具结果
   └─ 启用 Prompt Caching（cacheRetention）

3. 用量监控
   ├─ /usage tokens 实时查看每次回复成本
   ├─ /usage cost 查看累计成本
   └─ 设置 daily/weekly 预算告警（通过 Cron 实现）

18.8 远程部署与安全

18.8.1 Tailscale 集成（推荐）

Tailscale 是 OpenClaw 远程部署的最佳拍档：

# 一键启动（Tailscale Serve + HTTPS）
openclaw gateway --tailscale serve

# 访问
# https://<magicdns>/

Tailscale Serve 的好处：

• 自动 HTTPS（Let's Encrypt）
• Control UI/WebSocket 可通过 Tailscale 身份免 Token 认证（gateway.auth.allowTailscale: true）
• 不需要 SSH 隧道
• 不需要开放端口

18.8.2 远程沙盒（OpenShell）

OpenShell 是 OpenClaw 的远程沙盒后端——把代码执行放到云端而不是本地 Docker：

本地 Docker 后端 vs OpenShell 后端：

本地 Docker：
  ├─ 在本机运行容器
  ├─ 文件在本地
  └─ 受限于本机资源

OpenShell：
  ├─ 远程 SSH 执行
  ├─ 文件在云端
  ├─ 可选 GPU
  └─ 不受限于本机资源

两种工作空间模式：

	mirror（镜像）	remote（远程）
规范工作空间	本地主机	远程 OpenShell
同步方向	双向（每次 exec）	一次性种子
每轮开销	较高（上传+下载）	较低（直接远程操作）
本地编辑可见	是（下次 exec）	否（需 recreate）
适用场景	开发工作流	长期运行 Agent、CI

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",       // mirror 或 remote
          gpu: true,            // 需要 GPU 时
        },
      },
    },
  },
}

18.8.3 安全边界

安全层级：

1. Gateway 认证（token/password）
   └─ 保护所有 HTTP API 和 WebSocket 连接

2. DM 隔离（dmScope）
   └─ per-channel-peer 防止用户间会话泄露

3. 工具策略（tools.allow/deny）
   └─ 控制每个会话可用的工具

4. Exec 审批（elevated）
   └─ 高权限操作需要显式批准

5. 沙盒隔离（sandbox）
   └─ 代码执行在隔离环境中

6. HTTP 硬拒绝（gateway.tools.deny）
   └─ 即使策略允许，也阻止危险工具

18.9 多租户 SaaS 架构

基于 OpenClaw 构建多租户 SaaS，核心问题是隔离——不同租户的会话、配置、工具权限必须完全隔离。

18.9.1 单 Gateway 多租户

最简单的方案是在一个 Gateway 上通过 DM 隔离和多 Agent 路由实现多租户：

{
  // DM 隔离：每个通道+发送者一个独立会话
  session: { dmScope: "per-channel-peer" },

  // 多 Agent 路由：按通道分配不同 Agent
  agents: {
    list: [
      { id: "enterprise", default: true },
      { id: "personal" },
    ],
    routing: {
      // 企业 Slack → enterprise Agent
      // 个人 Telegram → personal Agent
    },
  },
}

局限性：所有租户共享同一个 Gateway 进程、同一个配置文件、同一套模型凭据。

18.9.2 多 Gateway 多租户

更健壮的方案是每个租户（或每组租户）运行独立的 Gateway：

┌──────────────────────────────────────────────────────┐
│                   多 Gateway 架构                      │
│                                                      │
│  租户 A                          租户 B              │
│  ┌─────────────┐                ┌─────────────┐    │
│  │  Gateway A  │                │  Gateway B  │    │
│  │  Port 18789│                │  Port 18790│    │
│  │  Agent: A   │                │  Agent: B   │    │
│  │  Model: X   │                │  Model: Y   │    │
│  └─────────────┘                └─────────────┘    │
│       │                               │              │
│       ▼                               ▼              │
│  ┌─────────────────────────────────────────┐         │
│  │           Nginx / Caddy 反代           │         │
│  │  /tenant-a/ → Gateway A              │         │
│  │  /tenant-b/ → Gateway B              │         │
│  └─────────────────────────────────────────┘         │
│                                                      │
└──────────────────────────────────────────────────────┘

每个 Gateway 有：

• 独立的配置文件
• 独立的模型凭据
• 独立的会话存储
• 独立的工具权限

18.9.3 白标定制

OpenClaw 的 identity 配置允许你自定义 Agent 的名称、主题和表情符号：

{
  identity: {
    name: "HelpBot",           // Agent 名称
    theme: "professional assistant",  // 主题描述（写入 SOUL.md）
    emoji: "🤖",               // 表情符号
  },
}

更深度的白标：

• 修改 Control UI 的 basePath（如 /assistant）
• 自定义 Control UI 的品牌色和 Logo
• 使用独立的模型提供商和 API Key
• 自定义 Skill 集合（每个租户不同的技能包）

18.10 社区产品案例

OpenClaw 的社区已经构建了大量真实产品，涵盖各个领域。以下是一些有代表性的案例：

18.10.1 开发者工具

PR Review → Telegram 反馈：OpenCode 完成代码修改 → 提交 PR → OpenClaw 审查 diff 并在 Telegram 中返回评审意见和合并建议。

Linear CLI：与 Agent 工作流集成的项目管理 CLI，管理 Issue、项目和工作流。

Beeper CLI：通过 Beeper 本地 MCP API 管理所有聊天（iMessage、WhatsApp 等）。

18.10.2 自动化

Tesco 超市自动购物：每周菜单 → 常规商品 → 预订配送时段 → 确认订单。没有 API，纯浏览器控制。

Slack 自动客服：监控公司 Slack 频道，自动回复帮助信息，将通知转发到 Telegram。

TradingView 技术分析：通过浏览器自动化登录 TradingView，截图图表并按需进行技术分析。

18.10.3 知识与记忆

WhatsApp 记忆库：导入完整的 WhatsApp 导出数据，转录 1000+ 条语音消息，与 Git 日志交叉验证，输出链接的 Markdown 报告。

Karakeep 语义搜索：使用 Qdrant + OpenAI/Ollama 嵌入为书签添加向量搜索。

18.10.4 多 Agent 编排

Dream Team（14+ Agent）：一个 Gateway 下运行 14+ 个 Agent，由 Opus 4.5 编排器委派给 Codex 工人。涵盖沙盒隔离、Webhook、心跳和委派流的完整架构。

18.10.5 硬件与 IoT

Bambu 3D 打印机控制：控制 BambuLab 打印机——状态、任务、摄像头、AMS、校准等。

Home Assistant Add-on：在 Home Assistant OS 上运行 OpenClaw Gateway，支持 SSH 隧道和持久化状态。

GoHome 自动化：基于 Nix 的家庭自动化系统，OpenClaw 作为界面，加上 Grafana 仪表盘。

18.10.6 语音与电话

Clawdia Phone Bridge：Vapi 语音助手 ↔ OpenClaw HTTP 桥接，实现近实时的电话通话。

Voice Call 插件：通过 Twilio/Telnyx/Plivo 拨打和接听电话，支持流式语音。

本章小结

• OpenClaw 内置 OpenAI 兼容 HTTP API（/v1/chat/completions），可以零适配接入 Open WebUI、LobeChat 等前端
• OpenResponses API（/v1/responses）支持基于 Item 的输入、客户端工具调用、图片/文件上传
• Tools Invoke API（/tools/invoke）允许直接调用单个工具，经过完整的策略链过滤
• Control UI 是内置的 Web 管理界面，提供聊天、通道管理、Cron、配置、调试等完整功能
• TUI 适合 SSH 远程使用，WebChat 是原生聊天 UI
• 用量追踪直接从 Provider 拉取真实数据，不估算成本
• Tailscale 集成是远程部署的最佳实践
• OpenShell 提供远程沙盒执行能力
• 多租户 SaaS 可以通过单 Gateway 多 Agent 路由或多 Gateway 架构实现
• 社区已构建了大量真实产品，涵盖开发者工具、自动化、IoT、语音等领域