clawgo/README.md

ClawGo

高性能、可长期运行的 Go 原生 AI Agent（支持多平台构建与多通道接入）。

English

---

一句话介绍

ClawGo = 单二进制网关 + 多通道消息 + 工具调用 + 自治执行 + 可审计记忆。

适合：

• 私有化 AI 助手
• 持续巡检/自动任务
• 多通道机器人（Telegram/Feishu/Discord 等）
• 需要可控、可追踪、可回滚的 Agent 系统

---

核心能力

• 双模式运行

  • clawgo agent：本地交互模式
  • clawgo gateway：服务化网关模式（推荐长期运行）

• 多通道支持

  • Telegram / Feishu / Discord / WhatsApp / QQ / DingTalk / MaixCam

• 工具与技能体系

  • 内置工具调用、技能安装与执行
  • 支持任务编排与子任务协同

• 自治与任务治理

  • 会话级自治（idle 预算、暂停/恢复）
  • Task Queue / Task Audit 分层治理
  • 自治任务冲突锁（resource_keys）

• 记忆与上下文治理

  • memory_search / 分层记忆
  • 自动上下文压缩
  • 启动自检与任务续跑

• 可靠性增强

  • Provider fallback（含 errsig-aware 排序）
  • 入站/出站去重（防重复收发）
  • 审计可观测（provider/model/source/channel）

---

EKG（Execution Knowledge Graph）

ClawGo 内置轻量 EKG（无需外部图数据库），用于降低重复错误与无效重试：

• 事件流：memory/ekg-events.jsonl
• 快照：memory/ekg-snapshot.json
• 错误签名归一化（路径/数字/hex 去噪）
• 重复错误抑制（可配置阈值）
• Provider fallback 历史打分（含错误签名维度）
• 与 Memory 联动（[EKG_INCIDENT] 结构化沉淀，支持提前拦截）
• WebUI 支持按 6h/24h/7d 时间窗口查看

---

快速开始

一键安装（install.sh）

• GitHub 脚本链接：https://github.com/YspCoder/clawgo/blob/main/install.sh
• 一键安装命令：

curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash

1) 初始化

clawgo onboard

2) 配置上游模型/代理

clawgo login

3) 查看状态

clawgo status

4) 本地模式

clawgo agent
clawgo agent -m "Hello"

5) 网关模式

# 注册并启用 systemd 服务
clawgo gateway
clawgo gateway start
clawgo gateway status

# 前台运行
clawgo gateway run

---

WebUI

访问：

http://<host>:<port>/webui?token=<gateway.token>

主要页面：

• Dashboard
• Chat
• Logs
• Skills
• Config
• Cron
• Nodes
• Memory
• Task Audit
• Tasks
• EKG

---

多平台构建（Make）

构建所有默认平台

make build-all

Linux 专项瘦身构建（不禁用通道）

make build-linux-slim

说明（仅 Linux）：

• 在不禁用任何通道能力前提下，启用 purego,netgo,osusergo 与 CGO_ENABLED=0，降低体积并减少动态库依赖。
• 可选叠加 COMPRESS_BINARY=1（若安装 upx）做进一步压缩。

默认矩阵：

• linux/amd64
• linux/arm64
• linux/riscv64
• darwin/amd64
• darwin/arm64
• windows/amd64
• windows/arm64

自定义平台矩阵

make build-all BUILD_TARGETS="linux/amd64 linux/arm64 darwin/arm64 windows/amd64"

极致瘦身构建（目标 <10MB）

make build COMPRESS_BINARY=1

说明：

• 默认已启用 -trimpath -buildvcs=false -s -w，可减少路径与符号信息。
• COMPRESS_BINARY=1 时会尝试使用 upx --best --lzma 进一步压缩可执行文件。
• 若环境未安装 upx，会自动跳过并给出提示，不影响构建成功。

打包与校验

make package-all

输出：

• build/*.tar.gz（Linux/macOS）
• build/*.zip（Windows）
• build/checksums.txt

---

GitHub Release 自动发布

已内置 .github/workflows/release.yml：

触发方式：

• 推送 tag：v*（如 v0.0.1）
• 手动触发（workflow_dispatch）

自动完成：

• 多平台编译
• 产物打包
• checksums 生成
• WebUI dist 打包
• 发布到 GitHub Releases

示例：

git tag v0.0.2
git push origin v0.0.2

---

常用命令

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]

---

配置与热更新

• 支持 clawgo config set/get/check/reload
• 严格 JSON 解析（未知字段会报错）
• 配置热更新失败自动回滚备份

Provider（providers.proxy / providers.proxies.<name>）新增开关：

• cross_session_call_id（bool，默认 false）
  • true：沿用 call_id 传 function_call_output
  • false：不传 call_id，改为传递 tool 结果内容（适合跨会话/聚合路由场景）

---

稳定性与审计建议

生产建议开启：

• 通道去重窗口配置
• task-audit heartbeat 默认过滤
• EKG 时间窗口观察（默认 24h）
• 定期查看 EKG Top errsig 与 provider 分数

---

License

请参考仓库中的 License 文件。