OpenClaw ⚡ 个人 AI Agent 网关系统

📖 概述

OpenClaw 是基于现代 C++17 构建的个人 AI Agent 网关系统。它通过 HTTP/WebSocket 提供统一的接入层，将用户消息路由至智能体核心，智能体调用 LLM 进行理解和任务规划，并通过技能系统执行具体操作（Shell、文件、网络等）。所有对话历史与用户偏好通过 SQLite3 持久化，实现长期记忆。

✨ 核心特性

• 现代 C++17 实现 — 模板元编程、智能指针、RAII、线程安全。
• HTTP + WebSocket 双协议 — 支持 REST API 和实时双向通信。
• LLM 任务规划 — 自然语言 → 多步技能序列 → 顺序执行。
• 记忆检索增强 — 关键词匹配 + TF-IDF 相关性 + 时间衰减算法。
• 技能热注册 — 支持动态添加自定义技能，无需修改核心代码。
• 多用户会话 — 按 userId 隔离对话历史、记忆和任务状态。
• 心跳与提醒 — 定期主动问候，保持用户参与。
• 安全防护 — shell 命令黑名单、路径遍历检查、超时控制。
• 生产级配置 — JSON 配置文件 + 环境变量覆盖。

⚡ 快速开始

最简单的使用方式：启动服务并通过 curl 发送消息。

# 1. 编译
git clone https://github.com/openclaw/openclaw.git
cd openclaw && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# 2. 配置 API Key（可选）
export OPENAI_API_KEY="sk-xxxxx"

# 3. 运行
./openclaw --config ../config.json

# 4. 发送消息
curl -X POST http://127.0.0.1:18789/message \
  -H "Content-Type: application/json" \
  -d '{"user_id":"alice","message":"帮我列出当前目录的文件"}'

# 5. WebSocket 连接
wscat -c ws://127.0.0.1:18789/ws?user_id=alice

📦 编译与依赖

依赖项: C++17 编译器、CMake ≥ 3.16、libcurl、SQLite3、nlohmann/json、cpp-httplib（header-only）。

# Ubuntu/Debian
sudo apt update
sudo apt install build-essential cmake libcurl4-openssl-dev libsqlite3-dev

# 下载 nlohmann/json (header)
wget https://github.com/nlohmann/json/releases/download/v3.11.2/json.hpp
sudo cp json.hpp /usr/local/include/

# 下载 cpp-httplib
wget https://raw.githubusercontent.com/yhirose/cpp-httplib/master/httplib.h
sudo cp httplib.h /usr/local/include/

# 编译
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

🏗️ 架构设计

核心抽象：Gateway 处理网络通信，Agent 负责业务逻辑，Skills 提供可执行动作，Memory 持久化数据。所有模块通过回调与依赖注入连接。

🌐 Gateway 网关

基于 cpp-httplib 实现，提供 HTTP REST 端点和 WebSocket 实时通道。支持连接管理、消息收发、广播、统计信息收集。

HTTP 端点

• POST /message — 发送消息，返回智能体响应。
• GET /stats — 获取连接数、消息总数、错误数。
• GET /health — 健康检查。
• GET /users — 获取在线用户列表。
• POST /send — 主动向指定用户推送消息。

WebSocket 端点

• ws://host:port/ws?user_id=xxx — 建立持久连接，支持双向实时通信。
• 自动处理 JSON 格式消息，支持 type 字段区分。

// 代码示例：创建网关并设置处理器
Gateway gateway;
gateway.setMessageHandler([](const std::string& msg, const std::string& uid) {
    return "Echo: " + msg;
});
gateway.start(18789, "127.0.0.1");

🧠 Agent 智能体

核心智能体，负责 LLM 调用、任务规划、执行编排、会话管理与记忆集成。

• processMessage(message, userId) — 主入口，返回响应文本。
• planTask(goal, userId) — 调用 LLM 将目标拆解为技能序列。
• executeTask(taskId, steps, output) — 顺序执行技能，支持进度回调。
• setTaskCallback(callback) — 设置任务进度通知回调。

🔧 Skills 技能系统

技能注册与执行引擎，内置 12+ 常用技能，支持动态扩展。

内置技能列表

💾 Memory 记忆系统

基于 SQLite3 的混合记忆存储，支持短期/长期记忆、用户偏好、关键词检索与相关性排序。

• 短期记忆 — 最近对话，自动过期清理。
• 长期记忆 — 重要事实，支持关键词检索 + 相关性评分。
• 偏好存储 — 键值对，用于用户配置。
• 时间衰减 — 旧记忆权重降低，保持新鲜度。

// 记忆检索示例
auto results = memory.retrieve(userId, "meeting schedule", 5);
for (auto& entry : results) {
    std::cout << entry.content << " (score: " << entry.relevance << ")\n";
}

🛠️ Utils 工具库

通用工具集合，涵盖字符串、路径、文件、命令执行、时间、URL、JSON、日志、随机数等。

⚙️ 配置说明

配置文件 config.json 采用 JSON 格式，支持环境变量覆盖（OPENAI_API_KEY）。

{
    "gateway": {
        "port": 18789,
        "host": "127.0.0.1"
    },
    "llm": {
        "api_key": "",           // 或从环境变量读取
        "model": "gpt-4",
        "base_url": "https://api.openai.com/v1",
        "temperature": 0.7,
        "max_tokens": 1000
    },
    "memory": {
        "db_path": "~/.openclaw/memory.db",
        "workspace": "~/.openclaw/workspace"
    },
    "skills": {
        "allow_shell": true,
        "allow_file_ops": true,
        "sandbox": true
    },
    "heartbeat": {
        "enabled": true,
        "interval": 1800
    },
    "logging": {
        "level": "info"
    }
}

📌 示例代码

发送消息并获取响应

#include "Agent.h"
#include "Gateway.h"

int main() {
    Agent agent;
    agent.initialize("config.json");
    
    Gateway gateway;
    gateway.setMessageHandler([&](const std::string& msg, const std::string& uid) {
        return agent.processMessage(msg, uid);
    });
    gateway.start(18789, "127.0.0.1");
    
    std::cout << "Server running...\n";
    std::cin.get();
    return 0;
}

自定义技能注册

Skills skills;
skills.registerSkill({
    "greet",
    "Say hello",
    {"name"},
    [](const std::vector<std::string>& args, std::string& out) -> bool {
        std::string name = args.empty() ? "friend" : args[0];
        out = "Hello, " + name + "!";
        return true;
    }
});

📡 API 接口

HTTP POST /message

请求: {"user_id": "alice", "message": "列出文件"}
响应: {"response": "file1.txt\nfile2.txt\n", "user_id": "alice", "timestamp": 1234567890}

WebSocket 消息格式

// 客户端发送
{"message": "帮我记住明天开会"}

// 服务端响应
{"type": "response", "message": "已记住", "user_id": "alice", "timestamp": 1234567890}

📊 性能指标

⚖️ 许可证