Skip to content

yonglehou/NGOClaw

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

43 Commits
.agents/workflows
.agents/workflows
 
 
docs
docs
 
 
gateway
gateway
 
 
sdk
sdk
 
 
shared/proto
shared/proto
 
 
webchat
webchat
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 

Repository files navigation

NGOClaw

Autonomous AI Agent Framework — Pure Go, batteries included
自主 AI Agent 框架 — 纯 Go 实现，开箱即用

Quick Start • Features • Architecture • Configuration • User Manual • SDK

MIT License Go 1.24+ DDD

NGOClaw is a self-hosted, autonomous AI agent running a full ReAct loop (Reason → Act → Observe) with 25 built-in tools, MCP protocol support, hot-pluggable skills/prompts, and multi-channel interfaces.

NGOClaw 是一个自托管的自主 AI Agent，运行完整的 ReAct 循环（推理→行动→观察），内置 25 个工具，支持 MCP 协议、热插拔技能/提示词系统和多通道接口。

📌 News

  • [2026-03-01] 🚀 Engine 架构 + 统一通道 — 新增 Engine 作为核心状态持有者，ChannelSender 接口实现通道无关消息发送，统一 message 工具替代 3 个 TG 专用工具，gRPC metadata 传递 chatID 解决跨进程上下文丢失
  • [2026-02-28] 🌐 WebChat UI 优化 — 重新设计消息气泡、侧边栏、消息对齐和间距，对齐 Open WebUI 设计规范
  • [2026-02-25] 🧠 智能 Prompt Dispatch — 根据模型能力动态调整 Prompt 详细度（detailed/concise/minimal），支持 intent 过滤
  • [2026-02-23] 🔗 Remote Deploy — CLI 一键部署到远端 Linux 设备，支持 systemd/procd/sysvinit
  • [2026-02-16] 📝 Prompt 架构重设计 — 三层架构（System/Workspace/Channel），热插拔组件，模型变体支持

✨ Features / 功能亮点

Feature / 功能 Description / 说明
🤖 ReAct Agent Loop Reason → Act → Observe with automatic multi-step planning / 推理→行动→观察，自动规划多步任务
🔧 27 Built-in Tools File I/O, async shell, web search, code intelligence, browser, media, git, LSP / 文件读写、异步 Shell、搜索、代码智能、浏览器、媒体发送
🌐 Remote Control Deploy & control remote machines via gRPC — auto cross-compile, multi-init-system, full tool proxy / 远程设备管控：自动交叉编译、多 init 系统支持、完整工具代理
🧩 MCP Protocol One-click integration with Model Context Protocol / 一键接入 MCP 外部服务
📦 Hot-Pluggable Skills 9 built-in + drop SKILL.md into ~/.ngoclaw/skills/ — auto-discovered / 9 个内置 + 放入即可自动发现
💬 Multi-Interface CLI (TUI) · Telegram Bot · HTTP API · gRPC · WebSocket · REPL
🔄 Multi-Provider OpenAI / Anthropic / Gemini / Bailian / MiniMax — priority routing / 优先级路由、自动容灾
🧠 Context Compression XML summarization + memory extraction + Daily Log / XML 摘要 + 记忆提取
🛡️ Tool Sandbox Process-level isolation with configurable policies / 进程级隔离，可配工具策略
⚡ Hot Config config.yaml + MCP JSON + Prompts all support hot-reload / 均支持热重载
📊 Observability EventBus + Monitoring + structured logging (Zap) / 结构化日志

🚀 Quick Start / 快速开始

Prerequisites / 前置依赖

  • Go 1.24+
  • At least one LLM Provider API key / 至少一个 LLM Provider API Key

Optional Dependencies / 可选依赖

Core features work without these. Only needed for specific tools: 核心功能无需以下依赖，仅特定工具需要：

Feature / 功能 Dependency / 依赖 Notes / 说明
web_search SearXNG instance Self-hosted metasearch engine. Configure URL in skill / 自建元搜索引擎
stock_analysis Python 3.10+ + Conda/venv pip install matplotlib pandas requests in your env / 股票分析技能
Long-term Memory Ollama + embedding model e.g. ollama pull qwen3-embedding. Configure in config.yaml / 向量记忆
Browser tools Chrome/Chromium CDP (Chrome DevTools Protocol) for browser_* tools / 浏览器自动化
Python skills Python 3.10+ + Conda/venv Set python_env in config.yaml / Python 技能运行环境

Build from Source / 源码编译

git clone https://github.com/ngoclaw/ngoclaw.git
cd ngoclaw
make build          # → bin/ngoclaw
make install        # → /usr/local/bin/ngoclaw (optional, requires sudo / 可选)

First Run / 首次运行

NGOClaw auto-creates ~/.ngoclaw/ with 20 seed files on first launch: NGOClaw 首次启动自动创建 ~/.ngoclaw/ 并生成 20 个种子文件：

~/.ngoclaw/
├── config.yaml              # Main config (fully commented) / 主配置（全注释）
├── soul.md                  # Agent personality / Agent 人格
├── prompts/                 # 9 prompt components / 提示词组件
│   ├── rules.md             # Operating rules / 操作规则
│   ├── coding.md            # Coding standards / 编码标准
│   ├── safety.md            # Tool safety + remote rules / 工具安全
│   ├── workflow.md          # R→E→V dev cycle / 开发循环
│   ├── compression.md       # Context compaction / 上下文压缩
│   ├── memory-rules.md      # Memory save rules / 记忆规则
│   ├── finance.md           # Financial analysis / 金融分析
│   └── variants/            # Model-specific variants / 模型变体
├── skills/                  # 9 built-in skills / 9 个内置技能
│   ├── systematic-debugging/    # R→E→V debugging / 系统化调试
│   ├── writing-plans/           # Implementation planning / 计划编写
│   ├── executing-plans/         # Batch execution / 分批执行
│   ├── brainstorming/           # Requirements exploration / 需求探索
│   ├── verification-before-completion/ # Evidence before claims / 完成前验证
│   ├── remote-deploy/           # Remote device management / 远端管理
│   ├── find-skills/             # Discover & install skills / 发现技能
│   ├── writing-skills/          # Create custom skills / 编写技能
│   └── using-superpowers/       # Skill awareness / 技能意识
├── memory/                  # Long-term memory / 长期记忆
└── logs/                    # Structured logs / 日志

Edit config with your LLM provider / 编辑配置填入 LLM Provider 信息：

agent:
  default_model: "your-provider/your-model"
  providers:
    - name: your-provider
      base_url: "https://api.example.com/v1"
      api_key: "your-api-key"
      models:
        - "your-provider/model-name"
      priority: 1

Launch / 启动：

ngoclaw          # Interactive CLI (TUI) / 交互式终端
ngoclaw serve    # Background service / 后台服务 (HTTP + Telegram + gRPC)

🏗️ Architecture / 架构

┌─────────────────────────────────────────────────────────────┐
│                    Interfaces Layer / 接口层                  │
│  CLI/TUI │ Telegram Bot │ HTTP API │ gRPC │ WebSocket │ REPL│
├─────────────────────────────────────────────────────────────┤
│                   Application Layer / 应用层                 │
│              ProcessMessageUseCase · AgentLoop               │
├─────────────────────────────────────────────────────────────┤
│                     Domain Layer / 领域层                     │
│  Entity │ ValueObject │ Service │ Tool │ Agent │ Memory      │
├─────────────────────────────────────────────────────────────┤
│                 Infrastructure Layer / 基础设施层             │
│  LLM Router│Tool Registry│Prompt Engine│Sandbox│EventBus    │
│  Persistence│Config│Monitoring│Plugin│VectorStore│Embedding  │
└─────────────────────────────────────────────────────────────┘

DDD Layered — Domain logic has zero external dependencies; infrastructure is swappable. DDD 分层 — 领域逻辑零外部依赖；基础设施可替换；接口层随意扩展。

Core Flow / 核心流程

User Input → Interface Routing → AgentLoop (ReAct)
用户输入       接口层路由              ↓
                           LLM Router (multi-provider failover / 多 Provider 容灾)
                                      ↓
                           Reason → Tool Call → Observe → Loop
                           推理       工具调用     观察     循环
                                      ↓
                           Context Compression (automatic / 自动)
                                      ↓
                           Response Output / 响应输出

⚙️ Configuration / 配置

Config priority (low → high) / 配置优先级（低→高）：

  1. Built-in defaults / 内置默认值
  2. ~/.ngoclaw/config.yaml — Global / 全局配置
  3. ./config.yaml — Project-local override / 项目本地覆盖
  4. NGOCLAW_* env vars / 环境变量

LLM Providers

agent:
  providers:
    - name: openai
      base_url: "https://api.openai.com/v1"
      api_key: "sk-..."
      models: ["openai/gpt-4o"]
      priority: 1

    - name: anthropic
      base_url: "https://api.anthropic.com/v1"
      api_key: "sk-ant-..."
      models: ["anthropic/claude-sonnet-4-20250514"]
      priority: 2

Telegram Bot

telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allow_ids: [YOUR_TELEGRAM_USER_ID]
  mode: polling

MCP Servers

Edit ~/.ngoclaw/mcp.json:

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/dir"]
    }
  ]
}

🔧 Built-in Tools / 内置工具 (27)

Tool Kind Description / 说明
run_command execute Async shell execution with background polling / 异步 Shell 执行
command_status read Check output/status of background command / 查看后台命令状态
send_input execute Send stdin to interactive command / 发送输入到交互式命令
read_file read Read file contents / 读取文件
write_file execute Create or overwrite files / 写入文件
edit_file execute Precise edits via search-and-replace / 精准编辑
list_dir read List directory contents / 列目录
grep_search read Regex search in files / 正则搜索
glob read Find files by glob pattern / 按模式查找文件
apply_patch execute Apply unified diff patches / 应用补丁
web_search fetch Web search via SearXNG / 互联网搜索
web_fetch fetch Fetch URL content / 抓取网页
git execute Safe git ops (status/diff/log/commit/show) / 安全 Git 操作
lint_fix execute Code quality checks (lint/test/build) / 代码质量检查
lsp read LSP (definition/references/hover/diagnostics) / 语言服务
repo_map read Generate codebase structure map / 代码地图
save_memory think Save facts to long-term memory / 长期记忆
update_plan think Create/update execution plans / 任务计划
spawn_agent execute Delegate to independent sub-agent / 子 Agent 委派
remote_exec execute Execute tools on remote machines via gRPC / 远端工具执行
list_remotes read List connected remote devices / 查看远端设备
send_photo execute Send photo via Telegram / 发送图片
send_document execute Send document via Telegram / 发送文件
mcp_manage execute Manage MCP servers / 管理 MCP 服务器
stock_analysis fetch Stock data & technical analysis / 股票分析
browser_navigate fetch Navigate browser to URL / 浏览器导航
browser_screenshot read Take page screenshot / 网页截图

🌐 Remote Control / 远程设备管控

NGOClaw can deploy itself to remote Linux machines and execute tools remotely via gRPC. NGOClaw 可以将自身部署到远程 Linux 设备，并通过 gRPC 远程执行工具。

# Deploy to a remote machine (auto: SSH probe → cross-compile → upload → install → start)
# 部署到远程机器（全自动：SSH 探测 → 交叉编译 → 上传 → 安装 → 启动）
ngoclaw remote deploy --host 192.168.1.100 --user root --password xxx --name MyServer

# Manage remotes / 管理远端
ngoclaw remote list              # List all remotes / 查看所有远端
ngoclaw remote activate MyServer # Activate remote / 激活远端
ngoclaw remote remove MyServer   # Remove remote / 移除远端

Supported architectures: amd64, arm64, mipsle (OpenWrt) 支持架构：amd64、arm64、mipsle（OpenWrt）

Supported init systems: systemd, procd, sysvinit, nohup fallback 支持 init 系统：systemd、procd、sysvinit、nohup 备选

Once deployed, use remote_exec tool to run any tool on the remote machine. 部署后，使用 remote_exec 工具在远端执行任意工具。

📦 Skill System / 技能系统

9 skills are built-in. Create custom skills by adding a directory with SKILL.md: 9 个技能内置。创建自定义技能只需添加目录和 SKILL.md：

---
name: my-skill
description: When to use this skill
---

# My Skill
Workflow instructions here...

Auto-discovered on startup. Install community skills via npx skills find <query>. 启动时自动发现。通过 npx skills find <query> 安装社区技能。

📁 Project Structure / 项目结构

ngoclaw/
├── gateway/                    # Go main program / Go 主程序
│   ├── cmd/
│   │   ├── cli/               # Unified binary: CLI + serve + remote mgmt + doctor
│   │   └── remote/            # Remote daemon (deployed to target machines)
│   ├── internal/
│   │   ├── domain/            # Domain layer (entities, services, tools) / 领域层
│   │   ├── application/       # Application layer (app.go, usecases) / 应用层
│   │   ├── infrastructure/    # Infrastructure (LLM, tools, prompt, sandbox, remote) / 基础设施层
│   │   └── interfaces/        # Interface layer (CLI, TG, HTTP, gRPC, WS) / 接口层
│   └── go.mod
├── sdk/                        # Client SDKs (Go, Python)
├── shared/                     # Shared protobuf definitions
├── docs/                       # Documentation / 文档
├── Makefile
└── LICENSE

🛠️ Tech Stack / 技术栈

Component / 组件 Technology / 技术
Language / 语言 Go 1.24
HTTP Gin
Telegram telegram-bot-api/v5
TUI Bubble Tea + Lip Gloss + Glamour
Database / 数据库 SQLite / PostgreSQL (GORM)
Logging / 日志 Zap
Config / 配置 Viper
Vector Store / 向量存储 LanceDB
gRPC google.golang.org/grpc

�📄 License / 许可证

MIT License

🤝 Contributing / 贡献

Contributions welcome! / 欢迎贡献！

  • Architecture / 架构: Respect DDD layering / 遵循 DDD 分层
  • Code Style / 代码风格: SOLID principles, components < 500 lines / SOLID 原则
  • Testing / 测试: Add tests for new tools and services / 新功能请附测试
  • Commits / 提交: Use conventional commit messages
  • Issues: Bug reports and feature requests via GitHub Issues
  • PRs: Fork → branch → implement → test → PR

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Go 92.8%
  • JavaScript 4.0%
  • CSS 1.9%
  • Python 0.6%
  • C 0.4%
  • Makefile 0.2%
  • Other 0.1%