mirror of
https://github.com/YspCoder/clawgo.git
synced 2026-04-15 06:17:28 +08:00
257 lines
4.8 KiB
Markdown
257 lines
4.8 KiB
Markdown
# ClawGo
|
|
|
|
A high-performance, long-running Go-native AI Agent with multi-platform builds and multi-channel messaging.
|
|
|
|
[中文](./README.md)
|
|
|
|
---
|
|
|
|
## What is ClawGo?
|
|
|
|
**ClawGo = single-binary gateway + channel integrations + tool calling + autonomy + auditable memory.**
|
|
|
|
Best for:
|
|
- Self-hosted AI assistants
|
|
- Continuous automation / inspections
|
|
- Multi-channel bots (Telegram/Feishu/Discord/...)
|
|
- Agent systems requiring control, traceability, and rollback safety
|
|
|
|
---
|
|
|
|
## Core Capabilities
|
|
|
|
- **Dual runtime modes**
|
|
- `clawgo agent`: local interactive mode
|
|
- `clawgo gateway`: service mode for long-running workloads
|
|
|
|
- **Multi-channel support**
|
|
- Telegram / Feishu / Discord / WhatsApp / QQ / DingTalk / MaixCam
|
|
|
|
- **Tools & skills**
|
|
- Built-in tool-calling and skill execution
|
|
- Task orchestration support
|
|
|
|
- **Autonomy & task governance**
|
|
- Session-level autonomy (idle budget, pause/resume)
|
|
- Task Queue + Task Audit governance
|
|
- Resource-key locking for conflict control
|
|
|
|
- **Memory & context governance**
|
|
- `memory_search` and layered memory
|
|
- Automatic context compaction
|
|
- Startup self-check and task continuation
|
|
|
|
- **Reliability hardening**
|
|
- Provider fallback (errsig-aware ranking)
|
|
- Inbound/outbound dedupe protection
|
|
- Better observability (provider/model/source/channel)
|
|
|
|
---
|
|
|
|
## EKG (Execution Knowledge Graph)
|
|
|
|
ClawGo includes a lightweight EKG (no external graph DB required):
|
|
|
|
- Event log: `memory/ekg-events.jsonl`
|
|
- Snapshot cache: `memory/ekg-snapshot.json`
|
|
- Normalized error signatures (path/number/hex denoise)
|
|
- Repeated-error suppression (configurable threshold)
|
|
- Historical provider scoring (including error-signature dimension)
|
|
- Memory linkage (`[EKG_INCIDENT]` structured notes for earlier suppression)
|
|
- WebUI time windows: `6h / 24h / 7d`
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### One-Click Install (install.sh)
|
|
|
|
- GitHub script link: <https://github.com/YspCoder/clawgo/blob/main/install.sh>
|
|
- One-click install command:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash
|
|
```
|
|
|
|
### 1) Initialize
|
|
|
|
```bash
|
|
clawgo onboard
|
|
```
|
|
|
|
### 2) Configure upstream model/proxy
|
|
|
|
```bash
|
|
clawgo login
|
|
```
|
|
|
|
### 3) Check status
|
|
|
|
```bash
|
|
clawgo status
|
|
```
|
|
|
|
### 4) Local mode
|
|
|
|
```bash
|
|
clawgo agent
|
|
clawgo agent -m "Hello"
|
|
```
|
|
|
|
### 5) Gateway mode
|
|
|
|
```bash
|
|
# register + enable systemd service
|
|
clawgo gateway
|
|
clawgo gateway start
|
|
clawgo gateway status
|
|
|
|
# foreground mode
|
|
clawgo gateway run
|
|
```
|
|
|
|
---
|
|
|
|
## WebUI
|
|
|
|
Access:
|
|
|
|
```text
|
|
http://<host>:<port>/webui?token=<gateway.token>
|
|
```
|
|
|
|
Main pages:
|
|
- Dashboard
|
|
- Chat
|
|
- Logs
|
|
- Skills
|
|
- Config
|
|
- Cron
|
|
- Nodes
|
|
- Memory
|
|
- Task Audit
|
|
- Tasks
|
|
- EKG
|
|
|
|
---
|
|
|
|
## Multi-Platform Build (Make)
|
|
|
|
### Build all default targets
|
|
|
|
```bash
|
|
make build-all
|
|
```
|
|
|
|
### Linux slim build (without disabling channels)
|
|
|
|
```bash
|
|
make build-linux-slim
|
|
```
|
|
|
|
Notes (Linux only):
|
|
- Keeps all channel capabilities while enabling `purego,netgo,osusergo` with `CGO_ENABLED=0` to reduce size and dynamic library coupling.
|
|
- Optionally combine with `COMPRESS_BINARY=1` (if `upx` is installed) for additional compression.
|
|
|
|
Default matrix:
|
|
- linux/amd64
|
|
- linux/arm64
|
|
- linux/riscv64
|
|
- darwin/amd64
|
|
- darwin/arm64
|
|
- windows/amd64
|
|
- windows/arm64
|
|
|
|
### Custom build matrix
|
|
|
|
```bash
|
|
make build-all BUILD_TARGETS="linux/amd64 linux/arm64 darwin/arm64 windows/amd64"
|
|
```
|
|
|
|
### Ultra-slim build (target <10MB)
|
|
|
|
```bash
|
|
make build COMPRESS_BINARY=1
|
|
```
|
|
|
|
Notes:
|
|
- Default build now uses `-trimpath -buildvcs=false -s -w` to remove path/symbol overhead.
|
|
- With `COMPRESS_BINARY=1`, the build will try `upx --best --lzma` for further executable compression.
|
|
- If `upx` is unavailable, build still succeeds and prints a warning.
|
|
|
|
### Package + checksums
|
|
|
|
```bash
|
|
make package-all
|
|
```
|
|
|
|
Outputs:
|
|
- `build/*.tar.gz` (Linux/macOS)
|
|
- `build/*.zip` (Windows)
|
|
- `build/checksums.txt`
|
|
|
|
---
|
|
|
|
## GitHub Release Automation
|
|
|
|
Built-in workflow: `.github/workflows/release.yml`
|
|
|
|
Triggers:
|
|
- tag push: `v*` (e.g. `v0.0.1`)
|
|
- manual dispatch (workflow_dispatch)
|
|
|
|
Pipeline includes:
|
|
- Multi-platform compilation
|
|
- Artifact packaging
|
|
- Checksum generation
|
|
- WebUI dist packaging
|
|
- GitHub Releases publishing
|
|
|
|
Example:
|
|
|
|
```bash
|
|
git tag v0.0.2
|
|
git push origin v0.0.2
|
|
```
|
|
|
|
---
|
|
|
|
## Common Commands
|
|
|
|
```text
|
|
clawgo onboard
|
|
clawgo login
|
|
clawgo status
|
|
clawgo agent [-m "..."]
|
|
clawgo gateway [run|start|stop|restart|status]
|
|
clawgo config set|get|check|reload
|
|
clawgo channel test ...
|
|
clawgo cron ...
|
|
clawgo skills ...
|
|
clawgo uninstall [--purge] [--remove-bin]
|
|
```
|
|
|
|
---
|
|
|
|
## Config & Hot Reload
|
|
|
|
- Supports `clawgo config set/get/check/reload`
|
|
- Strict JSON parsing (unknown fields fail fast)
|
|
- Auto rollback on failed hot reload
|
|
|
|
---
|
|
|
|
## Stability / Operations Notes
|
|
|
|
Recommended for production:
|
|
- tune channel dedupe windows
|
|
- keep heartbeat filtered in task-audit by default
|
|
- monitor EKG with 24h window baseline
|
|
- review Top errsig/provider score periodically
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
See repository License file.
|