ClawGo

面向生产的 Go 原生 Agent Runtime。

ClawGo 不是“又一个聊天壳子”，而是一套可长期运行、可观测、可恢复、可编排的 Agent 运行时。

• main agent 负责入口、路由、派发、汇总
• subagent runtime 负责本地或远端分支执行
• runtime store 持久化 run、event、thread、message、memory
• WebUI 负责检查、状态展示和账号管理，不负责运行时配置写入

English

为什么是 ClawGo

大多数 Agent 项目停留在：

• 一个聊天界面
• 一组工具调用
• 一段 prompt

ClawGo 更关注真正的运行时能力：

• 多 Agent 拓扑和内部协作流
• 可恢复的 subagent run
• 本地主控加远端 node 分支
• 配置、审计、日志、记忆的工程化闭环

一句话：

ClawGo 是 Agent Runtime，而不只是 Agent Chat。

核心能力

1. 多 Agent 拓扑

• 统一展示 main / subagents / remote branches
• 内部协作流与用户对话分离
• 子代理执行过程可追踪，但不会污染用户主通道

2. 可恢复执行

• subagent_runs.jsonl
• subagent_events.jsonl
• threads.jsonl
• agent_messages.jsonl
• 重启后可恢复进行中的 subagent run

3. 工程化配置

• config.json 管理 agent registry
• system_prompt_file -> AGENT.md
• WebUI 可查看状态、节点、账号与运行信息
• 运行时配置修改回到文件，不通过 WebUI 写入

4. 长期运行能力

• 本地优先
• Go 原生 runtime
• 多通道接入
• Task Audit / Logs / Memory / Skills / Config / Agents 全链路闭环

WebUI

WebUI 当前定位：

• Dashboard 与 Agent 拓扑查看
• 节点、日志、记忆、运行态检查
• OAuth 账号管理

WebUI 当前不负责：

• 修改 subagent/runtime 配置
• 查询或控制公开 task runtime

快速开始

1. 安装

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

2. 初始化

clawgo onboard

3. 选择服务商与模型

clawgo provider list
clawgo provider use openai/gpt-5.4
clawgo provider configure

如果服务商使用 OAuth，例如 codex、anthropic、gemini、kimi、qwen：

clawgo provider login codex
clawgo provider login codex --manual

如果同一个 provider 同时有 API key 和 OAuth 账号，推荐配置 auth: "hybrid"：

• 优先使用 api_key
• 额度或限流失败时自动切到 OAuth 账号池
• 仍保留多账号轮换和后台刷新

4. 启动

交互模式：

clawgo agent
clawgo agent -m "Hello"

网关模式：

clawgo gateway run

开发模式：

make dev

WebUI：

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

架构概览

默认协作模式：

user -> main -> worker -> main -> user

当前系统包含四层：

1. main agent 负责用户入口、路由、派发、汇总
2. local subagents 在 config.json -> agents.subagents 中声明，使用独立 session 和 memory namespace
3. node-backed branches 远端节点作为受控 agent 分支挂载到主拓扑
4. runtime store 保存运行态、线程、消息、事件和审计数据

说明：

• subagent_profile 保留，用来创建和管理 subagent 定义
• spawn 保留，用来触发 subagent 执行
• 公开 task runtime、WebUI 配置写入、EKG、watchdog 已移除

配置结构

当前有两层配置视图：

• 落盘文件继续使用原始结构
• 只读接口可暴露标准化视图：
  • core
  • runtime

推荐结构：

{
  "agents": {
    "defaults": {
      "context_compaction": {},
      "execution": {},
      "summary_policy": {}
    },
    "router": {
      "enabled": true,
      "main_agent_id": "main",
      "strategy": "rules_first",
      "policy": {
        "intent_max_input_chars": 1200,
        "max_rounds_without_user": 200
      },
      "rules": []
    },
    "communication": {},
    "subagents": {
      "main": {},
      "coder": {},
      "tester": {}
    }
  }
}

说明：

• runtime_control 已移除
• WebUI 配置编辑已禁用
• 运行时配置修改请直接改 config.json
• 启用中的本地 subagent 必须配置 system_prompt_file
• 远端分支需要：
  • transport: "node"
  • node_id
  • parent_agent_id

完整示例见 config.example.json。

MCP 服务支持

ClawGo 支持通过 tools.mcp 接入 stdio、http、streamable_http、sse 型 MCP server。

• 在 config.json -> tools.mcp.servers 中声明 server
• 启动时自动发现远端 MCP tools，并注册为本地工具
• 工具命名格式为 mcp__<server>__<tool>
• permission=workspace 时，working_dir 必须留在 workspace 内
• permission=full 时，working_dir 可以是任意绝对路径

Prompt 文件约定

推荐把 agent prompt 独立成文件：

• agents/main/AGENT.md
• agents/coder/AGENT.md
• agents/tester/AGENT.md

配置示例：

{
  "system_prompt_file": "agents/coder/AGENT.md"
}

规则：

• 路径必须是 workspace 内相对路径
• 仓库不内置这些示例 prompt
• 用户或 agent workflow 需要自行创建实际文件

记忆与运行态

ClawGo 不是所有 agent 共用一份上下文。

• main
  • 保存主记忆与协作摘要
• subagent
  • 使用独立 session key
  • 写入自己的 memory namespace
• runtime store
  • 持久化 runs、events、threads、messages
  • 内部仍可使用 task 建模，但不再暴露成公开控制面

这带来三件事：

• 更好恢复
• 更好追踪
• 更清晰的执行边界

适合谁

• 想用 Go 做 Agent Runtime 的开发者
• 想要可视化多 Agent 拓扑和内部协作流的团队
• 需要强观测、强审计、强恢复能力的系统
• 想把 agent 配置、prompt、工具权限工程化管理的团队

如果你想快速上手，先看 config.example.json，再跑一次 make dev。