# cppClaw

**Repository Path**: judeli/cppclaw

## Basic Information

- **Project Name**: cppClaw
- **Description**: cppClaw 是一个基于现代 C++23 打造的高性能、轻量级 AI 智能体(c++版本小龙虾），受 nanobot 和 OpenClaw 启发，具备 ReAct Agent 循环、可扩展工具系统、多渠道接入、灵活 JSON 配置，支持主流 LLM 提供商及长期记忆与会话持久化能力等，是将 AI Agent 带入 C++ 世界的原生解决方案。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <h1>🦞 cppClaw：C++ 原生 AI 助手框架</h1>

  <p>基于现代 C++23 打造的高性能、轻量级 AI Agent 框架</p>

  <p>
    <img src="https://img.shields.io/badge/C++-23-blue?style=flat&logo=c%2B%2B&logoColor=white" alt="C++23">
    <img src="https://img.shields.io/badge/CMake-3.22+-red?style=flat&logo=cmake&logoColor=white" alt="CMake">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
    <br>
    <strong>版本 0.1.0</strong>
  </p>

[English](README.md) | **中文**

</div>

---

## 🚀 概述

**cppClaw** 是一个基于现代 C++23 打造的 AI 助手框架，致力于将大语言模型的智能带入本地应用场景：

- ⚡ **极致性能**：编译型语言优势，毫秒级启动，内存占用仅约 10MB
- 🔧 **灵活配置**：JSON 配置文件，支持切换多种 LLM 提供商
- 🛡️ **隐私优先**：支持本地 Ollama 部署，数据无需出网
- 📦 **便携部署**：跨平台单二进制文件，无复杂依赖

### 灵感来源

受 [nanobot](https://github.com/HKUDS/nanobot) 和 [OpenClaw](https://github.com/openclaw/openclaw.git) 启发，cppClaw 将相同的理念带入 C++ 生态系统，专注于：

- **性能**：最小化运行时开销
- **便携性**：跨 Windows/Linux/macOS 的单二进制部署
- **可扩展性**：通过技能和工具的插件架构

---

## ✨ 功能特性

### 核心能力

| 功能 | 描述                                                 |
|------|----------------------------------------------------|
| **🧠 ReAct Agent** | Complete → Tool Calls → Execute → Iterate 循环，带安全保障 |
| **🛠️ 工具系统** | 文件操作、shell 执行、网络搜索、技能中心                            |
| **💬 多渠道** | CLI 本地使用，Gateway 对接 微信、飞书、钉钉、QQ(计划)                |
| **🔧 配置系统** | JSON 配置，支持 OpenAI/Anthropic/Ollama/智谱等             |
| **📚 技能** | GitHub、天气、摘要、自我改进等预置技能                             |
| **🧵 记忆系统** | 长期记忆（`MEMORY.md`）+ 会话历史持久化                         |

### 技术亮点

- **现代 C++23**：`std::expected`、ranges、协程、模块化等新特性，不乏现代编程语言的丝滑。
- **类型安全工具**：工具定义与执行的强类型约束
- **工作区沙箱**：安全优先的文件/命令访问控制

---

## 📊 对比

| Feature        | cppClaw      | PicoClaw (Golang)| NanoBot (Python) | OpenClaw (TypeScript) |
|----------------|--------------|------------------|----------------------|----------------------|
| **语言**         | C++23        | Golang 1.25+| Python 3.10+ | TypeScript/Node.js |
| **内存占用**       | ~10MB        | < 10MB | ~100MB | ~1GB+ |
| **启动时间**           | <10ms        | ~1s | ~5s | ~30s |
| **部署方式** | Single binary | Single binary| Python env + deps | Node.js + npm |
| **性能** | ⚡⚡⚡⚡         | ⚡⚡⚡ | ⚡⚡ | ⚡ |

*基于当前实现的估算值；实际使用因工作负载而异。

---


---

## 🏗️ 架构

### 目录结构

```
cpp-ai-assistant/
├── CMakeLists.txt              # CMake 根目录配置
├── config/                     # 配置管理
│   └── default.json            # 默认配置，init 时复制到 ~/.cppclaw/
├── third_party/                # header-only 库（内部依赖库目录为示例，按实际下载的为准）
│   ├── json/                   # nlohmann/json
│   ├── spdlog/                 # spdlog
│   ├── cereal/                 # cereal
│   ├── httplib/                # cpp-httplib
│   └── CMakeLists.txt          # 依赖库和自动下载配置
├── include/                    # 头文件目录。各自头文件工具、agent接口或抽象类封装。
│   ├── common/                 # 基础模块
│   │   ├── logger.hpp          # 日志封装
│   │   ├── serializer.hpp      # 序列化封装
│   │   ├── config.hpp          # 配置加载
│   │   ├── file_util.hpp       # 文件操作封装
│   │   ├── error.hpp           # 错误处理封装
│   │   ├── date_time.hpp       # 时间处理封装
│   │   ├── string_util.hpp     # 字符串处理封装
│   │   ├── uuid.hpp            # UUID 生成封装
│   │   ├── base64.hpp          # Base64 编码解码封装
│   │   ├── md5.hpp             # MD5 计算封装
│   │   ├── constants.hpp       # 公共常量定义。如多环境名称dev/prod/test，配置文件路径，日志默认级别，错误码等
│   │   └── expected.hpp        # expected 封装
│   ├── core/                   # 核心引擎
│   │   ├── agent_loop.hpp      # ReAct 循环
│   │   ├── context.hpp         # 上下文构建
│   │   ├── memory.hpp          # 记忆系统
│   │   ├── skills_loader.hpp   # 技能加载
│   │   └── task.hpp            # 任务定义
│   ├── llm/                    # LLM 提供商
│   │   ├── provider.hpp        # 统一接口
│   │   ├── provider_registry.hpp # Provider Registry
│   │   ├── openai.hpp          # OpenAI 实现
│   │   ├── anthropic.hpp       # Anthropic 实现
│   │   └── ollama.hpp          # Ollama 本地实现
│   ├── tools/                  # 工具系统
│   │   ├── tool_base.hpp       # 工具抽象
│   │   ├── shell_tool.hpp      # Shell 执行
│   │   ├── file_tool.hpp       # 文件读写操作
│   │   └── web_tool.hpp        # 网页搜索
│   ├── bus/                    # 消息总线
│   │   ├── message.hpp         # 消息定义
│   │   ├── event_queue.hpp     # 事件队列
│   │   └── channel.hpp         # 渠道抽象
│   ├── channels/               # 渠道实现
│   │   ├── cli_channel.hpp     # 命令行
│   │   └── http_channel.hpp    # HTTP API
│   ├── cron/                   # 定时任务
│   │   └── scheduler.hpp       # 任务调度
│   └── heartbeat/              # 主动唤醒
│       └── heartbeat.hpp       # HEARTBEAT.md 周期性任务
├── src/                        # 源代码
│   ├── apps/                   # 应用程序
│   │   ├── gateway/            # gateway 主程序
│   │   │   ├── main.cpp        # 主程序
│   │   │   └── CMakeLists.txt  # CMake 配置
│   │   └── cli/                # CLI 工具（init、status 等）
│   │       ├── main.cpp        # 主程序
│   │       └── CMakeLists.txt  # CMake 配置
│   ├── common/                 # libcppclaw_common
├── tests/                      # 单元测试
│   ├── p1/                     # 阶段1测试执行程序
│   ├── p2/                     # 阶段2测试执行程序    
│   ├── .../                    # 其他阶段测试执行程序    
│   └── CMakeLists.txt          # tests下执行程序公共CMake配置    
├── docs/                       # 文档
│   ├── prompt_example/         # 配置文档示例
│   │   ├── scripts/            # 构建脚本
│   │   ├── skills/             # 内置技能
│   │   ├── AGENTS.md           # 角色定义
│   │   ├── SOUL.md             # 性格与价值观
│   │   ├── TOOLS.md            # 拥有的工具
│   │   ├── USER.md             # 用户画像
│   │   └── HEARTBEAT.md        # 周期性任务
│   ├── 日志说明.md
│   ├── 测试情况.md
│   └── 编程规范.md
├── LICENSE     
├── README.md
├── README.zh.md
└── CMakeLists.txt
```

### 执行流程

```
用户输入 (CLI/Gateway)
    ↓
AgentLoop.run()
    ↓
ContextBuilder.build() → System Prompt + 消息
    ↓
LLM Provider.complete()
    ↓
有 tool_calls？
    ├─ 是 → 执行工具 → 写入结果 → 重复
    └─ 否 → 返回响应 → 保存到记忆
```

### 系统语境图（C4 Level 1 — Context）

**回答**：本系统是谁在用、和哪些外部系统打交道？

```mermaid
flowchart TB
    subgraph actors["人员"]
        U([终端用户])
    end

    subgraph sys["软件系统：cppclaw AI 助手"]
        direction TB
        S["自动化对话、工具调用与\n工作区记忆（C++）"]
    end

    subgraph ext["外部依赖"]
        OLL["Ollama\n(本地/局域网 LLM)"]
        OAI["OpenAI 兼容 API\n(可选云端)"]
        MMX["MiniMax API\n(可选云端)"]
    end

    subgraph fs["用户环境"]
        WS[("工作区目录\nSOUL.md / session / memory / …")]
        CFG[("配置文件\nconfig.json")]
        SKILLS[("skills/ 目录\n(SKILL.md 索引)")]
    end

    U -->|交互式 / -m 单轮 | S
    S -->|HTTPS/HTTP\nchat / complete| OLL
    S -->|HTTPS\nchat/completions| OAI
    S -->|HTTPS\nchat/completions| MMX
    S <-->|读写 | WS
    S <-->|加载 | CFG
    S <-->|读取技能索引 | SKILLS
```

**说明**：

- 实际 **LLM 提供商**由配置决定，支持 **Ollama**（本地）、**OpenAI** 或 **MiniMax**（云端），可切换。
- **工作区**与 **配置**在磁盘上；会话历史落在工作区下的 **`session/history.json`** 等（见阶段5 文档）。
- **skills/** 目录包含已安装的技能包，每个技能含 `SKILL.md` 定义文件。

---

### 容器图（C4 Level 2 — Containers）

**回答**：系统由哪些**可运行/可边界**的块组成、之间如何连接？

```mermaid
flowchart LR
    U([用户])

    subgraph deploy["本机进程"]
        CLI["cppclaw_cli\n(init / status / agent)"]
        GW["cppclaw_gateway\n(CLI 渠道 + Agent)"]
    end

    subgraph lib["共享库逻辑\n(libcppclaw_common)"]
        APP["agent_session\n(resolve workspace,\nagent_run_turn)"]
        CORE["AgentLoop\nContextBuilder\nMemoryStore"]
        LLM["ProviderRegistry\nOllama / OpenAI / MiniMax"]
        TOOL["ToolManager\nfile / shell / web_search"]
        SKILLS["SkillsLoader\n(skills/*/SKILL.md)"]
    end

    OLL["Ollama :11434"]
    OAI["OpenAI API"]
    MMX["MiniMax API"]
    DISK[("磁盘：workspace + config")]
    SKDISK[("skills/ 目录\n(SKILL.md 索引)")]

    U --> CLI
    U --> GW
    CLI --> APP
    GW --> APP
    APP --> CORE
    APP --> LLM
    APP --> TOOL
    APP --> SKILLS
    CORE --> LLM
    CORE --> TOOL
    CORE --> SKILLS
    LLM --> OLL
    LLM --> OAI
    LLM --> MMX
    CORE --> DISK
    APP --> DISK
    SKILLS --> SKDISK
```

**说明**：

- **CLI** 与 **Gateway** 是两个**入口进程**；核心逻辑在 **`cppclaw_common`**（含 `agent_session`、`AgentLoop`、LLM、工具等）。
- **Gateway** 当前以 **CLIChannel** 接 stdin/stdout；后续可扩展 HTTP 等渠道（规划见 `规划.md`）。
- **EventBus** 在 Gateway 内用于演示入站/出站队列；与 Agent 调用链并行存在。
- **SkillsLoader**：负责加载 `skills/*/SKILL.md` 索引，在 `ContextBuilder` 中注入技能摘要到 system prompt。
- **LLM Providers**：新增 **MiniMax** 提供商（与 Ollama/OpenAI 并列），通过 ProviderRegistry 统一管理。

---

## 🎯 快速开始

### 前置要求

| 要求 | 版本 | 说明 |
|------|------|------|
| **CMake** | ≥ 3.22 | 构建系统 |
| **编译器** | 支持 C++23 | GCC 13+、Clang 16+、MSVC 2022+ |
| **OpenSSL** | 可选 | HTTPS 支持（推荐） |

### 源码构建

```bash
# 克隆仓库
git clone https://gitee.com/judeli/cppclaw.git
cd cppclaw

# 配置
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# 构建
cmake --build build --target cppclaw_cli cppclaw_gateway

# 输出位于 build/bin/
```

## 📦 安装

### 预编译二进制（即将推出）

从 [Releases](https://gitee.com/judeli/cppclaw/tags) 页面下载。

解压安装包到指定目录（例如 /opt/cppclaw）
```bash
unzip cppclaw-linux-x64.zip -d /opt/cppclaw
```

解压后的安装根目录:
```
cppclaw/    
├── bin/                             
│   ├── cppclaw_cli     
│   └── cppclaw_gateway
├── skills/                          
│   ├── create-agent-skills/
│   ├── weather/
│   └── ...
└── config/
    ├── default.json
    └── ...
```

### 首次运行

```bash
# 初始化工作区 (~/.cppclaw/)
./cppclaw_cli init

# 编辑配置
vim ~/.cppclaw/config.json

# 测试简单查询
./cppclaw_cli agent -m "你好！你能做什么？"
```

---

## ⚙️ 配置

### 配置文件位置

默认：`~/.cppclaw/config.json`

### 基础配置

```json
{
  "agent": {
    "name": "钢铁龙虾",
    "profession": "AI 助手",
    "system_prompt": "",
    "max_iterations": 10,
    "working_directory": "~/.cppclaw/workspace"
  },
  "llm": {
    "provider": "ollama",
    "model": "qwen3.5:4b",
    "base_url": "http://localhost:11434/v1",
    "api_key": "",
    "max_tokens": 4096,
    "temperature": 0.7
  },
  "tools": {
    "shell_enabled": true,
    "file_enabled": true,
    "web_search_enabled": true,
    "skill_hub_enabled": true,
    "clawhub_api_base": "https://wry-manatee-359.convex.site"
  }
}
```

### 支持的 LLM 提供商

| 提供商 | 模型格式 | 获取 API Key |
|--------|----------|-------------|
| **Ollama** | `ollama/{model}` | 本地（无需 key） |
| **OpenAI** | `openai/{model}` | [platform.openai.com](https://platform.openai.com) |
| **Kimi** | `kimi/{model}` | [platform.moonshot.cn](https://platform.moonshot.cn) |
| **MiniMax** | `minimax/{model}` | [platform.minimaxi.com](https://platform.minimaxi.com) |
| **千问 (Qwen)** | `qwen/{model}` | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
| **豆包 (Doubao)** | `doubao/{model}` | [www.volcengine.com](https://www.volcengine.com) |
| **DeepSeek** | `deepseek/{model}` | [platform.deepseek.com](https://platform.deepseek.com) |
| **智谱 AI** | `zhipu/{model}` | [bigmodel.cn](https://bigmodel.cn) |
| **Anthropic** | `anthropic/{model}` | [console.anthropic.com](https://console.anthropic.com) |

### 工作区结构

```
~/.cppclaw/workspace/
├── sessions/          # 会话历史
├── memory/
│   ├── MEMORY.md     # 长期事实
│   └── YYYY-MM-DD.md # 每日笔记
├── skills/           # 自定义技能
├── AGENTS.md         # Agent 指南
├── SOUL.md           # 人格与价值观
├── USER.md           # 用户偏好
└── TOOLS.md          # 工具文档
```

---

## 💬 使用方式

### CLI 模式

```bash
# 一次性查询
./cppclaw_cli agent -m "列出当前目录下的文件"

# 交互模式
./cppclaw_cli agent

# 指定自定义工作区
./cppclaw_cli agent -w /path/to/workspace -m "帮我..."
```

### Gateway 模式（聊天平台）

```bash
# 启动 Telegram/Discord Gateway
./cppclaw_gateway

# 在 ~/.cppclaw/config.json 中配置 channels
```

#### 示例：Telegram 设置(待定)

1. 通过 [@BotFather](https://t.me/BotFather) 创建机器人
2. 复制 Token 到配置：

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}
```

3. 运行 gateway，与你的机器人聊天！

---

## 🛠️ 工具系统

### 内置工具

| 工具 | 操作 | 描述 |
|------|------|------|
| **file** | read/write/append/list/delete | 工作区范围内的文件操作 |
| **shell** | execute | 带安全过滤的命令执行 |
| **web_search** | search | 网络搜索（需要 API key） |
| **skill_hub** | search/install/uninstall | ClawHub 技能管理 |

### 安全沙箱

默认情况下，cppClaw 运行在沙箱环境中：

- ✅ 文件访问限制在工作区内
- ✅ 危险命令被拦截（`rm -rf`、`format` 等）
- ✅ 长时间运行操作有超时限制

禁用限制（⚠️ 安全风险，暂不支持）：

```json
{
  "agent": {
    "restrict_to_workspace": false
  }
}
```

---

## 📚 技能

预装技能：

| 技能 | 描述 |
|------|------|
| **github** | 通过 `gh` CLI 集成 GitHub |
| **weather** | 当前天气与预报 |
| **summarize** | URL/文件摘要 |
| **self-improving-agent** | 从错误中持续学习 |
| **create-agent-skills** | 创建新技能的指南 |

### 使用技能

技能从 `skills/` 目录自动加载。使用技能：

```markdown
用户："查看北京的天气"
→ Agent 加载：skills/weather/SKILL.md
→ 执行天气工具
→ 返回天气预报
```

### ClawHub

安装社区技能，当前直接对话安装即可，命令行方式暂未支持。

```bash
# 搜索 ClawHub
cppclaw_cli skill search "code-review"

# 安装技能
cppclaw_cli skill install code-review-assistant
```

---

## 🤝 贡献

欢迎 PR！代码库设计为可读且可扩展。

### 如何贡献

1. Fork 仓库
2. 创建功能分支
3. 进行修改
4. 运行测试
5. 提交 Pull Request

### 需要帮助的领域

- 🚀 性能优化（SIMD、异步 I/O）
- 🌍 更多渠道集成（Discord、QQ、企业微信）
- 🧪 测试覆盖扩展
- 📚 ClawHub 技能开发
- 🐛 Bug 修复与平台兼容性

---

## 🔒 安全

### 沙箱机制

- 默认启用工作区限制
- 危险命令模式被拦截
- 文件访问验证

### 漏洞报告

请通过 GitHub Private Vulnerability Reporting（如果启用）或直接联系维护者报告安全问题。

---

## 📄 许可证

**MIT License** - 详见 [LICENSE](LICENSE)。

### 第三方依赖

| 库 | 许可证 | 用途 |
|----|--------|------|
| spdlog | MIT | 日志 |
| nlohmann/json | MIT | JSON 处理 |
| httplib | BSD-3 | HTTP 服务器/客户端 |
| cereal | BSD-3 | 序列化 |

---

## 🙏 致谢

- [nanobot](https://github.com/HKUDS/nanobot) - 原始灵感
- [OpenClaw](https://github.com/openclaw/openclaw.git) - 架构参考
- [spdlog](https://github.com/gabime/spdlog) - 快速 C++ 日志
- [nlohmann/json](https://github.com/nlohmann/json) - 现代 C++ JSON

---

## 📬 联系方式

- **GitHub Issues**: [报告 Bug / 功能请求](https://gitee.com/judeli/cppclaw/issues)
- **Discussions**: [社区论坛](https://github.com/your-org/cppclaw/discussions) (planning)

---

<div align="center">
  <p><strong>🦞 cppClaw — 将 AI Agent 带入 C++！</strong></p>
  <p>使用现代 C++23 构建，用 ❤️ 打造</p>
</div>