fix start check

2026-04-20 12:27:33 +08:00 · 2026-02-18 01:54:44 +08:00
parent e64129e814
commit 66faa0d79c
3 changed files with 422 additions and 385 deletions
--- a/README.md
+++ b/README.md
@@ -2,227 +2,143 @@

 [English](./README_EN.md)

-**ClawGo** 是一个为 Linux 服务器量身定制的高性能 AI 助手。通过 Go 语言的并发优势与二进制分发特性，它能以极低的资源占用提供完整的 Agent 能力。
+**ClawGo** 是一个面向 Linux 服务器的 Go 原生 AI Agent。它提供单二进制部署、多通道接入、可热更新配置与可控风险执行，适合长期在线自动化任务。

-## 🚀 核心优势
+## 🚀 功能总览

- **⚡ 纯净运行**：专为 Linux 服务器环境优化，不依赖 Node.js 或 Python。
- **🏗️ 生产级稳定**：单二进制文件部署，完美集成到 systemd 等服务管理工具。
- **🔌 强制上游代理**：通过 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 统一管理模型配额与鉴权。
- **🧩 强力技能扩展**：内置 `coding-agent`、`github`、`context7` 等生产力工具。
+- **双运行模式**：支持本地交互模式（`agent`）与服务化网关模式（`gateway`）。
+- **多通道接入**：支持 Telegram、Discord、Feishu、WhatsApp、QQ、DingTalk、MaixCam。
+- **自主协作能力**：支持自然语言驱动的自主执行、自动学习与启动自检。
+- **多智能体编排**：支持 Pipeline 协议（`role + goal + depends_on + shared_state`）。
+- **记忆与上下文治理**：支持分层记忆、`memory_search` 与自动上下文压缩。
+- **可靠性增强**：模型请求支持 fallback，覆盖配额、路由、网关瞬时错误等场景。
+- **安全防护**：Shell Risk Gate、Sentinel 巡检与自动修复能力。
+- **技能扩展**：支持内置技能与 GitHub 技能安装，支持原子脚本执行。

 ## 🏁 快速开始

-**1. 初始化**
+1. 初始化配置与工作区
+
 ```bash
 clawgo onboard
 ```
-运行 `clawgo gateway` 时会弹出 `yes/no`，可选择是否授予 root 权限。
-若选择 `yes`，会以 `sudo` 重新执行命令，并启用高权限策略（仅强制禁止 `rm -rf /`）。

-**2. 配置 CLIProxyAPI**
-ClawGo 强制要求使用 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 作为模型接入层。
+2. 配置上游代理（必需）
+
 ```bash
 clawgo login
 ```

-**3. 开始运行**
-```bash
-# 交互模式
-clawgo agent
+3. 检查当前状态

-# 后台网关模式 (支持 Telegram/Discord 等)
+```bash
+clawgo status
+```
+
+4. 交互式使用（本地）
+
+```bash
+clawgo agent
+# 或单轮消息
+clawgo agent -m "Hello"
+```
+
+5. 启动网关服务（用于 Telegram/Discord 等）
+
+```bash
+# 注册服务（systemd）
 clawgo gateway

-# 网关服务管理
+# 服务管理
 clawgo gateway start
 clawgo gateway restart
 clawgo gateway stop
+clawgo gateway status
+
+# 前台运行
+clawgo gateway run
+```
+
+## 📌 命令总览
+
+```text
+clawgo onboard                     初始化配置和工作区
+clawgo login                       配置 CLIProxyAPI 上游
+clawgo status                      查看配置、工作区、模型和日志状态
+clawgo agent [-m "..."]           本地交互模式
+clawgo gateway [...]               注册/运行/管理网关服务
+clawgo config set|get|check|reload 配置读写、校验与热更新
+clawgo channel test ...            通道连通性测试
+clawgo cron ...                    定时任务管理
+clawgo skills ...                  技能安装/查看/卸载
+clawgo uninstall [--purge] [--remove-bin]
+```
+
+全局参数：
+
+```bash
+clawgo --config /path/to/config.json <command>
+clawgo --debug <command>
 ```

 ## ⚙️ 配置管理与热更新

-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
 ```

-全局支持自定义配置文件：
+说明：
+- `enable` 会自动映射到 `enabled`。
+- `config set` 使用原子写入。
+- 网关运行时若热更新失败，会自动回滚备份，避免损坏配置。
+- `--config` 指定的自定义配置路径会被 `config` 命令与通道内 `/config` 指令一致使用。

-```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
+/config get <path>
+/config set <path> <value>
 /reload
-```
-
-自治控制命令（可选，推荐直接自然语言）：
-
-```text
 /autonomy start [idle]
 /autonomy stop
 /autonomy status
 /autolearn start [interval]
 /autolearn stop
 /autolearn status
-```
-
-消息调度策略（按会话 `session_key`）：
- 同一会话严格 FIFO 串行执行，后续消息进入队列等待。
- `/stop` 会立即中断当前回复，并继续处理队列中的下一条消息。
- 不同会话可并发执行，互不影响。
-
-## 🧭 自主模式与自然语言控制
-
- 自主模式/自动学习控制采用 **LLM 语义解析优先**（多语言），不依赖固定中文关键词。
- 规则解析仅作为兜底（如显式命令：`/autonomy ...`、`/autolearn ...`）。
- 开启自主模式时若附带研究方向，系统会优先按该方向执行；当用户表示方向完成后，会自动切换到其他高价值任务继续推进。
- 进度回报使用自然语言，不使用固定阶段编号模板。
-
-系统会在启动时读取 `AGENTS.md`、`SOUL.md`、`USER.md` 作为行为约束与语义解析上下文。
-
-## 🧩 Onboard/Install 文档同步
-
- `clawgo onboard` 与 `make install` 都会同步 `AGENTS.md`、`SOUL.md`、`USER.md` 到工作区。
- 若文件不存在：创建。
- 若文件已存在：仅更新 `CLAWGO MANAGED BLOCK` 受管区块，保留用户自定义内容（增量更新，不整文件覆盖）。
-
-## 🧾 日志链路
-
-默认启用文件日志，并支持自动分割和过期清理（默认保留 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": ""
-}
-```
-
-Cron 调度策略支持配置化（支持热更新）：
-
-```json
-"cron": {
-  "min_sleep_sec": 1,
-  "max_sleep_sec": 30,
-  "retry_backoff_base_sec": 30,
-  "retry_backoff_max_sec": 1800,
-  "max_consecutive_failure_retries": 5,
-  "max_workers": 4
-}
-```
-
-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>
 ```

-## 🧠 记忆与索引增强
+调度语义（按 `session_key`）：
+- 同会话严格 FIFO 串行处理。
+- `/stop` 会中断当前回复并继续队列后续消息。
+- 不同会话并发执行，互不阻塞。

- `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
-  }
-}
+```bash
+clawgo channel test --channel telegram --to <chat_id> -m "ping"
 ```

-上下文自动压缩配置：
+## 🧠 记忆、自主与上下文压缩
+
+- 启动会读取 `AGENTS.md`、`SOUL.md`、`USER.md` 作为行为约束与语义上下文。
+- 网关启动后会执行一次自检任务，结合历史会话与 `memory/HEARTBEAT.md` 判断是否继续未完成任务。
+- 上下文压缩同时按消息数量阈值和上下文体积阈值触发，控制 token 成本与长会话稳定性。
+- 分层记忆支持 `profile / project / procedures / recent notes`。
+
+上下文压缩配置示例：

 ```json
 "agents": {
@@ -238,35 +154,135 @@ Shell 工具默认启用 Risk Gate。检测到破坏性命令时，默认阻断
 }
 ```

-也可以热更新：
+## 🤖 多智能体编排 (Pipeline)

-```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
+内置标准化编排工具：
+- `pipeline_create`
+- `pipeline_status`
+- `pipeline_state_set`
+- `pipeline_dispatch`
+- `spawn`（支持 `pipeline_id/task_id/role`）
+
+适用于拆解复杂任务、跨角色协作和共享状态推进。
+
+## 🛡️ 风险防护与稳定性
+
+- **Model fallback**：主模型失败时可回退到候选模型，覆盖限流、配额、网关瞬时异常、上游路由异常。
+- **HTTP 兼容处理**：可识别非 JSON 错页并给出响应预览；兼容从 `<function_call>` 文本块提取工具调用。
+- **Shell Risk Gate**：高风险命令默认阻断，支持 dry-run 与 force 策略。
+- **Sentinel**：周期巡检配置/内存/日志目录，支持自动修复与告警转发。
+
+Sentinel 配置示例：
+
+```json
+"sentinel": {
+  "enabled": true,
+  "interval_sec": 60,
+  "auto_heal": true,
+  "notify_channel": "",
+  "notify_chat_id": ""
+}
 ```

-## 🗺️ Repo-Map 与原子技能
+## ⏱️ 定时任务 (Cron)

- `repo_map`：生成并查询代码全景地图，先定位目标文件再精读。
- `skill_exec`：执行 `skills/<name>/scripts/*` 原子脚本，保持 Gateway 精简。
+```bash
+clawgo cron list
+clawgo cron add -n "daily-check" -m "检查待办" -c "0 9 * * *"
+clawgo cron add -n "heartbeat" -m "汇报状态" -e 300
+clawgo cron enable <job_id>
+clawgo cron disable <job_id>
+clawgo cron remove <job_id>
+```

-## 📦 迁移与技能
+`cron add` 支持：
+- `-n, --name` 任务名
+- `-m, --message` 发给 agent 的消息
+- `-e, --every` 每 N 秒执行
+- `-c, --cron` cron 表达式
+- `-d, --deliver --channel <name> --to <id>` 投递到消息通道

-ClawGo 现在集成了原 OpenClaw 的所有核心扩展能力：
- **coding-agent**: 结合 Codex/Claude Code 实现自主编程。
- **github**: 深度集成 `gh` CLI，管理 Issue、PR 及 CI 状态。
- **context7**: 针对代码库与文档的智能上下文搜索。
+## 🧩 技能系统

-## 🛠️ 安装 (仅限 Linux)
+技能管理命令：
+
+```bash
+clawgo skills list
+clawgo skills search
+clawgo skills show <name>
+clawgo skills install <github-repo>
+clawgo skills remove <name>
+clawgo skills install-builtin
+clawgo skills list-builtin
+```
+
+说明：
+- 支持从 GitHub 仓库安装技能（例如 `owner/repo/skill`）。
+- 支持安装内置技能到工作区。
+- 支持 `skill_exec` 原子执行 `skills/<name>/scripts/*`。
+
+## 🗂️ 工作区与文档同步
+
+默认工作区通常为 `~/.clawgo/workspace`，关键目录：
+
+```text
+workspace/
+  memory/
+    MEMORY.md
+    HEARTBEAT.md
+  skills/
+  AGENTS.md
+  SOUL.md
+  USER.md
+```
+
+`clawgo onboard` 与 `make install` 会同步 `AGENTS.md`、`SOUL.md`、`USER.md`：
+- 文件不存在则创建。
+- 文件存在则仅更新 `CLAWGO MANAGED BLOCK` 区块，保留用户自定义内容。
+
+## 🧾 日志
+
+默认启用文件日志，支持轮转和保留：
+
+```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`、`output_content_length`、`transcript_length`。
+
+## 🛠️ 安装与构建（Linux）

-### 从源码编译
 ```bash
 cd clawgo
 make build
 make install
 ```

+可选构建参数：
+
+```bash
+# 默认 1：剥离符号，减小体积
+make build STRIP_SYMBOLS=1
+
+# 保留调试符号
+make build STRIP_SYMBOLS=0
+```
+
+## 🧹 卸载
+
+```bash
+clawgo uninstall
+clawgo uninstall --purge
+clawgo uninstall --remove-bin
+```
+
 ## 📜 许可证

-MIT 许可证。 🦐
+MIT License.
--- a/README_EN.md
+++ b/README_EN.md
@@ -2,227 +2,143 @@

 [中文](./README.md)

-**ClawGo** is a high-performance AI assistant tailored for Linux servers. Leveraging the concurrency advantages and binary distribution of the Go language, it provides full agent capabilities with minimal resource overhead.
+**ClawGo** is a Go-native AI agent for Linux servers. It provides single-binary deployment, multi-channel integration, hot-reloadable config, and controllable execution risk for long-running autonomous workflows.

-## 🚀 Key Advantages
+## 🚀 Feature Overview

- **⚡ Native Performance**: Optimized specifically for Linux server environments, with no dependency on Node.js or Python.
- **🏗️ Production-Ready**: Single binary deployment, perfectly integrates with service management tools like systemd.
- **🔌 Mandatory Upstream Proxy**: Centralized management of model quotas and authentication via [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).
- **🧩 Powerful Skill Extension**: Built-in productivity tools like `coding-agent`, `github`, and `context7`.
+- **Dual runtime modes**: local interactive mode (`agent`) and service-oriented gateway mode (`gateway`).
+- **Multi-channel integration**: Telegram, Discord, Feishu, WhatsApp, QQ, DingTalk, MaixCam.
+- **Autonomous collaboration**: natural-language autonomy, auto-learning, and startup self-check.
+- **Multi-agent orchestration**: built-in Pipeline protocol (`role + goal + depends_on + shared_state`).
+- **Memory and context governance**: layered memory, `memory_search`, and automatic context compaction.
+- **Reliability enhancements**: model fallback for quota, routing, and transient gateway failures.
+- **Safety controls**: Shell Risk Gate, Sentinel inspection, and auto-heal support.
+- **Skill extensibility**: built-in skills plus GitHub skill installation and atomic script execution.

 ## 🏁 Quick Start

-**1. Initialize**
+1. Initialize config and workspace
+
 ```bash
 clawgo onboard
 ```
-When running `clawgo gateway`, a `yes/no` prompt asks whether to grant root privileges.
-If `yes`, the command is re-executed via `sudo` and a high-permission shell policy is enabled (with `rm -rf /` still hard-blocked).

-**2. Configure CLIProxyAPI**
-ClawGo requires [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) as the model access layer.
+2. Configure upstream proxy (required)
+
 ```bash
 clawgo login
 ```

-**3. Start Running**
-```bash
-# Interactive mode
-clawgo agent
+3. Check runtime status

-# Gateway mode (supports Telegram, Discord, etc.)
+```bash
+clawgo status
+```
+
+4. Run local interactive mode
+
+```bash
+clawgo agent
+# or one-shot message
+clawgo agent -m "Hello"
+```
+
+5. Start gateway service (for Telegram/Discord/etc.)
+
+```bash
+# register systemd service
 clawgo gateway

-# Gateway service management
+# service control
 clawgo gateway start
 clawgo gateway restart
 clawgo gateway stop
+clawgo gateway status
+
+# foreground run
+clawgo gateway run
 ```

-## ⚙️ Config Management & Hot Reload
+## 📌 Command Reference

-ClawGo can update `config.json` from CLI and trigger hot reload for a running gateway:
+```text
+clawgo onboard                     Initialize config and workspace
+clawgo login                       Configure CLIProxyAPI upstream
+clawgo status                      Show config/workspace/model/logging status
+clawgo agent [-m "..."]           Local interactive mode
+clawgo gateway [...]               Register/run/manage gateway service
+clawgo config set|get|check|reload Config CRUD, validation, hot reload
+clawgo channel test ...            Channel connectivity test
+clawgo cron ...                    Scheduled job management
+clawgo skills ...                  Skill install/list/remove/show
+clawgo uninstall [--purge] [--remove-bin]
+```
+
+Global flags:
+
+```bash
+clawgo --config /path/to/config.json <command>
+clawgo --debug <command>
+```
+
+## ⚙️ Config Management and Hot Reload
+
+Update config values directly from CLI and trigger gateway hot reload:

 ```bash
-# Set config value (supports enable -> enabled alias)
 clawgo config set channels.telegram.enable true
-
-# Read config value
 clawgo config get channels.telegram.enabled
-
-# Validate config
 clawgo config check
-
-# Trigger hot reload manually (sends SIGHUP to gateway)
 clawgo config reload
 ```

-Global custom config path:
+Notes:
+- `enable` is normalized to `enabled`.
+- `config set` uses atomic write.
+- If gateway reload fails while running, config auto-rolls back from backup.
+- Custom `--config` path is consistently used by CLI config commands and in-channel `/config` commands.

-```bash
-clawgo --config /path/to/config.json status
-```
+## 🌐 Channels and Message Control

-Or via environment variable:
-
-```bash
-export CLAWGO_CONFIG=/path/to/config.json
-```
-
-`config set` now uses atomic write, and if gateway is running but hot reload fails, it rolls back to backup automatically.
-
-Slash commands are also supported in chat channels:
+Supported in-channel slash commands:

 ```text
 /help
 /stop
 /status
-/config get channels.telegram.enabled
-/config set channels.telegram.enabled true
+/config get <path>
+/config set <path> <value>
 /reload
-```
-
-Autonomy control commands (optional; natural language is recommended):
-
-```text
 /autonomy start [idle]
 /autonomy stop
 /autonomy status
 /autolearn start [interval]
 /autolearn stop
 /autolearn status
-```
-
-Message scheduling policy (per `session_key`):
- Same session runs in strict FIFO order; later messages are queued.
- `/stop` immediately cancels the current response, then processing continues with the next queued message.
- Different sessions can run concurrently.
-
-## 🧭 Autonomy Mode & Natural-Language Control
-
- Autonomy/auto-learning controls are interpreted with **LLM semantic parsing first** (multi-language), instead of fixed keyword matching.
- Rule-based parsing is used only as a fallback (for explicit forms such as `/autonomy ...` and `/autolearn ...`).
- If a focus direction is provided when starting autonomy mode, execution prioritizes that focus; when user says it is complete, the agent switches to other high-value tasks automatically.
- Progress updates are natural-language messages, not rigid stage-number templates.
-
-At startup, `AGENTS.md`, `SOUL.md`, and `USER.md` are loaded as behavior constraints and semantic context.
-
-## 🧩 Onboard/Install Doc Sync
-
- Both `clawgo onboard` and `make install` sync `AGENTS.md`, `SOUL.md`, `USER.md` into workspace.
- If a file does not exist: it is created.
- If a file already exists: only the `CLAWGO MANAGED BLOCK` section is updated; user custom content is preserved (incremental update, no whole-file overwrite).
-
-## 🧾 Logging Pipeline
-
-File logging is enabled by default with automatic rotation and retention cleanup (3 days by default):
-
-```json
-"logging": {
-  "enabled": true,
-  "dir": "~/.clawgo/logs",
-  "filename": "clawgo.log",
-  "max_size_mb": 20,
-  "retention_days": 3
-}
-```
-
-Structured logging keys are now unified across channels and gateway:
- `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`
-
-Constants are centralized in `pkg/logger/fields.go`.
-
-## 🛡️ Sentinel & Risk Protection
-
-Sentinel periodically checks critical runtime resources (config, memory, log directories), with optional auto-heal and notify:
-
-```json
-"sentinel": {
-  "enabled": true,
-  "interval_sec": 60,
-  "auto_heal": true,
-  "notify_channel": "",
-  "notify_chat_id": ""
-}
-```
-
-Cron scheduling runtime strategy is configurable (and hot-reloadable):
-
-```json
-"cron": {
-  "min_sleep_sec": 1,
-  "max_sleep_sec": 30,
-  "retry_backoff_base_sec": 30,
-  "retry_backoff_max_sec": 1800,
-  "max_consecutive_failure_retries": 5,
-  "max_workers": 4
-}
-```
-
-Shell risk gate is enabled by default. Destructive commands are blocked unless explicitly forced:
-
-```json
-"tools": {
-  "shell": {
-    "risk": {
-      "enabled": true,
-      "allow_destructive": false,
-      "require_dry_run": true,
-      "require_force_flag": true
-    }
-  }
-}
-```
-
-## 🤖 Multi-Agent Orchestration (Pipeline)
-
-Task protocol is standardized with: `role + goal + depends_on + shared_state`.
-
-Available tools:
- `pipeline_create`: create a task graph
- `pipeline_status`: inspect pipeline status
- `pipeline_state_set`: write shared state
- `pipeline_dispatch`: dispatch currently runnable tasks
- `spawn`: supports `pipeline_id/task_id/role`
-
-Channel commands:
-
-```text
 /pipeline list
 /pipeline status <pipeline_id>
 /pipeline ready <pipeline_id>
 ```

-## 🧠 Memory & Context Indexing
+Scheduling semantics (`session_key` based):
+- Strict FIFO processing per session.
+- `/stop` interrupts current response and continues queued messages.
+- Different sessions are processed concurrently.

- `memory_search`: structured indexing (inverted index + cache)
- Memory layers: `profile / project / procedures / recent notes`
- Automatically Compacted Context: when a session gets long, it auto-summarizes and trims history
+Channel test example:

-```json
-"memory": {
-  "layered": true,
-  "recent_days": 3,
-  "layers": {
-    "profile": true,
-    "project": true,
-    "procedures": true
-  }
-}
+```bash
+clawgo channel test --channel telegram --to <chat_id> -m "ping"
 ```

-Automatic context compaction config:
+## 🧠 Memory, Autonomy, and Context Compaction
+
+- On startup, the agent loads `AGENTS.md`, `SOUL.md`, and `USER.md` as behavior and semantic constraints.
+- Gateway startup triggers a self-check task using history and `memory/HEARTBEAT.md` to decide whether unfinished tasks should continue.
+- Context compaction is triggered by both message-count and transcript-size thresholds.
+- Layered memory supports `profile / project / procedures / recent notes`.
+
+Context compaction config example:

 ```json
 "agents": {
@@ -238,35 +154,135 @@ Automatic context compaction config:
 }
 ```

-Hot-update examples:
+## 🤖 Multi-Agent Orchestration (Pipeline)

-```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
+Built-in orchestration tools:
+- `pipeline_create`
+- `pipeline_status`
+- `pipeline_state_set`
+- `pipeline_dispatch`
+- `spawn` (supports `pipeline_id/task_id/role`)
+
+Useful for complex task decomposition, role-based execution, and shared state workflows.
+
+## 🛡️ Safety and Reliability
+
+- **Model fallback**: retries with fallback models on quota/rate limits, transient gateway failures, and upstream auth-routing errors.
+- **HTTP compatibility handling**: detects non-JSON error pages with body preview; parses tool calls from `<function_call>` blocks.
+- **Shell Risk Gate**: blocks destructive operations by default; supports dry-run and force policies.
+- **Sentinel**: periodic checks for config/memory/log resources with optional auto-heal and notifications.
+
+Sentinel config example:
+
+```json
+"sentinel": {
+  "enabled": true,
+  "interval_sec": 60,
+  "auto_heal": true,
+  "notify_channel": "",
+  "notify_chat_id": ""
+}
 ```

-## 🗺️ Repo-Map & Atomic Skills
+## ⏱️ Scheduled Jobs (Cron)

- `repo_map`: build/query repository map before deep file reads
- `skill_exec`: execute `skills/<name>/scripts/*` atomically to keep gateway slim
+```bash
+clawgo cron list
+clawgo cron add -n "daily-check" -m "check todo" -c "0 9 * * *"
+clawgo cron add -n "heartbeat" -m "report status" -e 300
+clawgo cron enable <job_id>
+clawgo cron disable <job_id>
+clawgo cron remove <job_id>
+```

-## 📦 Migration & Skills
+`cron add` options:
+- `-n, --name` job name
+- `-m, --message` agent input message
+- `-e, --every` run every N seconds
+- `-c, --cron` cron expression
+- `-d, --deliver --channel <name> --to <id>` deliver response to a channel

-ClawGo now integrates all core extended capabilities from the original OpenClaw:
- **coding-agent**: Autonomous programming using Codex/Claude Code.
- **github**: Deep integration with `gh` CLI for managing issues, PRs, and CI status.
- **context7**: Intelligent context search for codebases and documentation.
+## 🧩 Skills

-## 🛠️ Installation (Linux Only)
+Skill management commands:
+
+```bash
+clawgo skills list
+clawgo skills search
+clawgo skills show <name>
+clawgo skills install <github-repo>
+clawgo skills remove <name>
+clawgo skills install-builtin
+clawgo skills list-builtin
+```
+
+Notes:
+- Install skills from GitHub (for example `owner/repo/skill`).
+- Install built-in skills into workspace.
+- Execute atomic scripts through `skill_exec` from `skills/<name>/scripts/*`.
+
+## 🗂️ Workspace and Managed Docs
+
+Default workspace is typically `~/.clawgo/workspace`:
+
+```text
+workspace/
+  memory/
+    MEMORY.md
+    HEARTBEAT.md
+  skills/
+  AGENTS.md
+  SOUL.md
+  USER.md
+```
+
+`clawgo onboard` and `make install` sync `AGENTS.md`, `SOUL.md`, `USER.md`:
+- Create file if missing.
+- Update only `CLAWGO MANAGED BLOCK` if file exists, preserving user custom sections.
+
+## 🧾 Logging
+
+File logging is enabled by default with rotation and retention:
+
+```json
+"logging": {
+  "enabled": true,
+  "dir": "~/.clawgo/logs",
+  "filename": "clawgo.log",
+  "max_size_mb": 20,
+  "retention_days": 3
+}
+```
+
+Recommended structured fields for querying/alerting:
+`channel`, `chat_id`, `sender_id`, `preview`, `error`, `message_content_length`, `assistant_content_length`, `output_content_length`, `transcript_length`.
+
+## 🛠️ Build and Install (Linux)

-### Build from Source
 ```bash
 cd clawgo
 make build
 make install
 ```

+Optional build flag:
+
+```bash
+# default: strip symbols for smaller binary
+make build STRIP_SYMBOLS=1
+
+# keep debug symbols
+make build STRIP_SYMBOLS=0
+```
+
+## 🧹 Uninstall
+
+```bash
+clawgo uninstall
+clawgo uninstall --purge
+clawgo uninstall --remove-bin
+```
+
 ## 📜 License

-MIT License. 🦐
+MIT License.
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -1555,8 +1555,8 @@ func (al *AgentLoop) RunStartupSelfCheckAllSessions(ctx context.Context, prompt,
 	}

 	keys := al.sessions.ListSessionKeys()
-	seen := make(map[string]struct{}, len(keys)+1)
-	sessions := make([]string, 0, len(keys)+1)
+	seen := make(map[string]struct{}, len(keys))
+	sessions := make([]string, 0, len(keys))
 	for _, key := range keys {
 		key = strings.TrimSpace(key)
 		if key == "" {
@@ -1568,11 +1568,9 @@ func (al *AgentLoop) RunStartupSelfCheckAllSessions(ctx context.Context, prompt,
 		seen[key] = struct{}{}
 		sessions = append(sessions, key)
 	}
-	if _, ok := seen[fallbackSessionKey]; !ok {
-		sessions = append(sessions, fallbackSessionKey)
-	}
 	report.TotalSessions = len(sessions)

+	// 仅对历史会话做压缩，避免启动时在每个历史会话重复执行自检任务。
 	for _, sessionKey := range sessions {
 		select {
 		case <-ctx.Done():
@@ -1591,21 +1589,28 @@ func (al *AgentLoop) RunStartupSelfCheckAllSessions(ctx context.Context, prompt,
 		if after < before {
 			report.CompactedSessions++
 		}
-
-		runCtx, cancel := context.WithTimeout(ctx, 90*time.Second)
-		_, err := al.ProcessDirect(runCtx, prompt, sessionKey)
-		cancel()
-		if err != nil {
-			report.FailedSessions++
-			logger.WarnCF("agent", "Startup self-check task failed", map[string]interface{}{
-				"session_key":     sessionKey,
-				logger.FieldError: err.Error(),
-			})
-			continue
-		}
-		report.CheckedSessions++
 	}

+	select {
+	case <-ctx.Done():
+		return report
+	default:
+	}
+
+	// 自检任务始终只执行一次，默认写入 gateway 启动专用会话。
+	runCtx, cancel := context.WithTimeout(ctx, 90*time.Second)
+	_, err := al.ProcessDirect(runCtx, prompt, fallbackSessionKey)
+	cancel()
+	if err != nil {
+		report.FailedSessions++
+		logger.WarnCF("agent", "Startup self-check task failed", map[string]interface{}{
+			"session_key":     fallbackSessionKey,
+			logger.FieldError: err.Error(),
+		})
+		return report
+	}
+	report.CheckedSessions = 1
+
 	return report
 }