mirror of
https://github.com/YspCoder/clawgo.git
synced 2026-04-13 23:07:33 +08:00
234 lines
5.9 KiB
Markdown
234 lines
5.9 KiB
Markdown
# ClawGo: 高性能 Go 语言 AI 助手 (Linux Server 专用)
|
||
|
||
[English](./README_EN.md)
|
||
|
||
**ClawGo** 是一个为 Linux 服务器量身定制的高性能 AI 助手。通过 Go 语言的并发优势与二进制分发特性，它能以极低的资源占用提供完整的 Agent 能力。
|
||
|
||
## 🚀 核心优势
|
||
|
||
- **⚡ 纯净运行**：专为 Linux 服务器环境优化，不依赖 Node.js 或 Python。
|
||
- **🏗️ 生产级稳定**：单二进制文件部署，完美集成到 systemd 等服务管理工具。
|
||
- **🔌 强制上游代理**：通过 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 统一管理模型配额与鉴权。
|
||
- **🧩 强力技能扩展**：内置 `coding-agent`、`github`、`context7` 等生产力工具。
|
||
|
||
## 🏁 快速开始
|
||
|
||
**1. 初始化**
|
||
```bash
|
||
clawgo onboard
|
||
```
|
||
运行 `clawgo gateway` 时会弹出 `yes/no`，可选择是否授予 root 权限。
|
||
若选择 `yes`，会以 `sudo` 重新执行命令，并启用高权限策略（仅强制禁止 `rm -rf /`）。
|
||
|
||
**2. 配置 CLIProxyAPI**
|
||
ClawGo 强制要求使用 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 作为模型接入层。
|
||
```bash
|
||
clawgo login
|
||
```
|
||
|
||
**3. 开始运行**
|
||
```bash
|
||
# 交互模式
|
||
clawgo agent
|
||
|
||
# 后台网关模式 (支持 Telegram/Discord 等)
|
||
clawgo gateway
|
||
|
||
# 网关服务管理
|
||
clawgo gateway start
|
||
clawgo gateway restart
|
||
clawgo gateway stop
|
||
```
|
||
|
||
## ⚙️ 配置管理与热更新
|
||
|
||
ClawGo 支持直接通过命令修改 `config.json`，并向运行中的网关发送热更新信号：
|
||
|
||
```bash
|
||
# 设置配置（支持 enable -> enabled 自动映射）
|
||
clawgo config set channels.telegram.enable true
|
||
|
||
# 读取配置
|
||
clawgo config get channels.telegram.enabled
|
||
|
||
# 校验配置
|
||
clawgo config check
|
||
|
||
# 手动触发热更新（向 gateway 发送 SIGHUP）
|
||
clawgo config reload
|
||
```
|
||
|
||
全局支持自定义配置文件：
|
||
|
||
```bash
|
||
clawgo --config /path/to/config.json status
|
||
```
|
||
|
||
也可使用环境变量：
|
||
|
||
```bash
|
||
export CLAWGO_CONFIG=/path/to/config.json
|
||
```
|
||
|
||
`config set` 采用原子写入，并在网关运行且热更新失败时自动回滚到备份，避免配置损坏导致服务不可用。
|
||
|
||
也支持在聊天通道中使用斜杠命令：
|
||
|
||
```text
|
||
/help
|
||
/stop
|
||
/status
|
||
/config get channels.telegram.enabled
|
||
/config set channels.telegram.enabled true
|
||
/reload
|
||
```
|
||
|
||
消息调度策略（按会话 `session_key`）：
|
||
- 同一会话严格 FIFO 串行执行，后续消息进入队列等待。
|
||
- `/stop` 会立即中断当前回复，并继续处理队列中的下一条消息。
|
||
- 不同会话可并发执行，互不影响。
|
||
|
||
## 🧾 日志链路
|
||
|
||
默认启用文件日志，并支持自动分割和过期清理（默认保留 3 天）：
|
||
|
||
```json
|
||
"logging": {
|
||
"enabled": true,
|
||
"dir": "~/.clawgo/logs",
|
||
"filename": "clawgo.log",
|
||
"max_size_mb": 20,
|
||
"retention_days": 3
|
||
}
|
||
```
|
||
|
||
当前通道与网关链路日志已统一为结构化字段，建议告警与检索统一使用：
|
||
- `channel`
|
||
- `chat_id`
|
||
- `sender_id`
|
||
- `preview`
|
||
- `error`
|
||
- `message_content_length`
|
||
- `assistant_content_length`
|
||
- `user_response_content_length`
|
||
- `fetched_content_length`
|
||
- `output_content_length`
|
||
- `transcript_length`
|
||
|
||
字段常量已集中在 `pkg/logger/fields.go`，新增日志字段建议优先复用常量，避免命名漂移。
|
||
|
||
## 🛡️ Sentinel 与风险防护
|
||
|
||
Sentinel 会周期巡检关键运行资源（配置、memory、日志目录），支持自动修复与告警转发：
|
||
|
||
```json
|
||
"sentinel": {
|
||
"enabled": true,
|
||
"interval_sec": 60,
|
||
"auto_heal": true,
|
||
"notify_channel": "",
|
||
"notify_chat_id": ""
|
||
}
|
||
```
|
||
|
||
Shell 工具默认启用 Risk Gate。检测到破坏性命令时，默认阻断并要求 `force=true`，可先做 dry-run：
|
||
|
||
```json
|
||
"tools": {
|
||
"shell": {
|
||
"risk": {
|
||
"enabled": true,
|
||
"allow_destructive": false,
|
||
"require_dry_run": true,
|
||
"require_force_flag": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🤖 多智能体编排 (Pipeline)
|
||
|
||
新增标准化任务编排协议：`role + goal + depends_on + shared_state`。
|
||
|
||
可用工具：
|
||
- `pipeline_create`：创建任务图
|
||
- `pipeline_status`：查看流水线状态
|
||
- `pipeline_state_set`：写入共享状态
|
||
- `pipeline_dispatch`：自动派发当前可执行任务
|
||
- `spawn`：支持 `pipeline_id/task_id/role` 参数
|
||
|
||
通道内可查看状态：
|
||
|
||
```text
|
||
/pipeline list
|
||
/pipeline status <pipeline_id>
|
||
/pipeline ready <pipeline_id>
|
||
```
|
||
|
||
## 🧠 记忆与索引增强
|
||
|
||
- `memory_search`：增加结构化索引（倒排索引 + 缓存），优先走索引检索。
|
||
- 记忆分层：支持 `profile / project / procedures / recent notes`。
|
||
- 自动上下文压缩（Automatically Compacted Context）：会话过长时自动生成摘要并裁剪历史，降低 token 开销与卡顿风险。
|
||
|
||
```json
|
||
"memory": {
|
||
"layered": true,
|
||
"recent_days": 3,
|
||
"layers": {
|
||
"profile": true,
|
||
"project": true,
|
||
"procedures": true
|
||
}
|
||
}
|
||
```
|
||
|
||
上下文自动压缩配置：
|
||
|
||
```json
|
||
"agents": {
|
||
"defaults": {
|
||
"context_compaction": {
|
||
"enabled": true,
|
||
"trigger_messages": 60,
|
||
"keep_recent_messages": 20,
|
||
"max_summary_chars": 6000,
|
||
"max_transcript_chars": 20000
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
也可以热更新：
|
||
|
||
```bash
|
||
clawgo config set agents.defaults.context_compaction.enabled true
|
||
clawgo config set agents.defaults.context_compaction.trigger_messages 80
|
||
clawgo config set agents.defaults.context_compaction.keep_recent_messages 24
|
||
```
|
||
|
||
## 🗺️ Repo-Map 与原子技能
|
||
|
||
- `repo_map`：生成并查询代码全景地图，先定位目标文件再精读。
|
||
- `skill_exec`：执行 `skills/<name>/scripts/*` 原子脚本，保持 Gateway 精简。
|
||
|
||
## 📦 迁移与技能
|
||
|
||
ClawGo 现在集成了原 OpenClaw 的所有核心扩展能力：
|
||
- **coding-agent**: 结合 Codex/Claude Code 实现自主编程。
|
||
- **github**: 深度集成 `gh` CLI，管理 Issue、PR 及 CI 状态。
|
||
- **context7**: 针对代码库与文档的智能上下文搜索。
|
||
|
||
## 🛠️ 安装 (仅限 Linux)
|
||
|
||
### 从源码编译
|
||
```bash
|
||
cd clawgo
|
||
make build
|
||
make install
|
||
```
|
||
|
||
## 📜 许可证
|
||
|
||
MIT 许可证。 🦐
|