Autonomous AI Agent Framework โ Pure Go, batteries included
่ชไธป AI Agent ๆกๆถ โ ็บฏ Go ๅฎ็ฐ๏ผๅผ็ฎฑๅณ็จ
Quick Start โข Features โข Architecture โข Configuration โข User Manual โข SDK
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 ๅ่ฎฎใ็ญๆๆๆ่ฝ/ๆ็คบ่ฏ็ณป็ปๅๅค้้ๆฅๅฃใ
- [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๏ผ๏ผ็ญๆๆ็ปไปถ๏ผๆจกๅๅไฝๆฏๆ
| 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) / ็ปๆๅๆฅๅฟ |
- Go 1.24+
- At least one LLM Provider API key / ่ณๅฐไธไธช LLM Provider API Key
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 ๆ่ฝ่ฟ่ก็ฏๅข |
git clone https://github.com/ngoclaw/ngoclaw.git
cd ngoclaw
make build # โ bin/ngoclaw
make install # โ /usr/local/bin/ngoclaw (optional, requires sudo / ๅฏ้)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: 1Launch / ๅฏๅจ๏ผ
ngoclaw # Interactive CLI (TUI) / ไบคไบๅผ็ป็ซฏ
ngoclaw serve # Background service / ๅๅฐๆๅก (HTTP + Telegram + gRPC)โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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 ๅๅฑ โ ้ขๅ้ป่พ้ถๅค้จไพ่ต๏ผๅบ็ก่ฎพๆฝๅฏๆฟๆข๏ผๆฅๅฃๅฑ้ๆๆฉๅฑใ
User Input โ Interface Routing โ AgentLoop (ReAct)
็จๆท่พๅ
ฅ ๆฅๅฃๅฑ่ทฏ็ฑ โ
LLM Router (multi-provider failover / ๅค Provider ๅฎน็พ)
โ
Reason โ Tool Call โ Observe โ Loop
ๆจ็ ๅทฅๅ
ท่ฐ็จ ่งๅฏ ๅพช็ฏ
โ
Context Compression (automatic / ่ชๅจ)
โ
Response Output / ๅๅบ่พๅบ
Config priority (low โ high) / ้ ็ฝฎไผๅ ็บง๏ผไฝโ้ซ๏ผ๏ผ
- Built-in defaults / ๅ ็ฝฎ้ป่ฎคๅผ
~/.ngoclaw/config.yamlโ Global / ๅ จๅฑ้ ็ฝฎ./config.yamlโ Project-local override / ้กน็ฎๆฌๅฐ่ฆ็NGOCLAW_*env vars / ็ฏๅขๅ้
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: 2telegram:
bot_token: "YOUR_BOT_TOKEN"
allow_ids: [YOUR_TELEGRAM_USER_ID]
mode: pollingEdit ~/.ngoclaw/mcp.json:
{
"servers": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@anthropic/mcp-filesystem", "/path/to/dir"]
}
]
}| 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 / ็ฝ้กตๆชๅพ |
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 ๅทฅๅ
ทๅจ่ฟ็ซฏๆง่กไปปๆๅทฅๅ
ทใ
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> ๅฎ่ฃ
็คพๅบๆ่ฝใ
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
| 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 |
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