goclaw (🐾 狗爪)

Go 语言版本的 OpenClaw - 一个功能强大的 AI Agent 框架。

功能特性

• 🛠️ 完整的工具系统：FileSystem、Shell、Web、Browser，支持 Docker 沙箱与权限控制
• 📚 技能系统 (Skills)：兼容 OpenClaw 和 AgentSkills 规范，支持自动发现与环境准入控制 (Gating)
• 💾 持久化会话：基于 JSONL 的会话存储，支持完整的工具调用链 (Tool Calls) 记录与恢复
• 📢 多渠道支持：Telegram、WhatsApp、飞书 (Feishu)、QQ、企业微信 (WeWork)、钉钉 (DingTalk)、百度如流 (Infoflow)、Gotify、Slack、Discord、Google Chat、Microsoft Teams、微信 (Weixin)
• 🔧 灵活配置：支持 YAML/JSON 配置，热加载，环境变量支持
• 🎯 多 LLM 提供商：OpenAI、Qianfan（百度千帆，OpenAI-compatible）、Anthropic、OpenRouter，支持故障转移
• 🌐 WebSocket Gateway：内置网关服务，支持实时通信
• ⏰ Cron 调度：内置定时任务调度器
• 🖥️ Browser 自动化：基于 Chrome DevTools Protocol 的浏览器控制
• 🧠 记忆系统：支持内置向量数据库和 QMD (Quick Markdown Database)
• 👥 多账号支持：每个通道支持配置多个账号实例
• 🪟 跨平台：支持 Linux、macOS、Windows

技能系统 (New!)

goclaw 引入了先进的技能系统，允许用户通过编写 Markdown 文档 (SKILL.md) 来扩展 Agent 的能力。

特性

• Prompt-Driven: 技能本质上是注入到 System Prompt 中的指令集，指导 LLM 使用现有工具 (exec, read_file 等) 完成任务。
• OpenClaw 兼容: 完全兼容 OpenClaw 的技能生态。您可以直接将 openclaw/skills 目录下的技能复制过来使用。
• 自动准入 (Gating): 智能检测系统环境。例如，只有当系统安装了 curl 时，weather 技能才会生效；只有安装了 git 时，git-helper 才会加载。

使用方法

配置文件加载优先级

goclaw 按以下顺序查找配置文件（找到第一个即使用）：

1. ~/.goclaw/config.json (用户全局目录，最高优先级)
2. ./config.json (当前目录)
3. 环境变量 GOSKILLS_* 前缀

可通过 --config 参数指定配置文件路径覆盖默认行为。支持 YAML 和 JSON 格式。

Skills 加载顺序

技能按以下顺序加载，同名技能后面的会覆盖前面的：

| 顺序 | 路径 | 说明 | |-----|------|------| | 1 | ~/.goclaw/skills/ | 用户全局目录（最低优先级） | | 2 | ${WORKSPACE}/skills/ | 工作区目录 | | 3 | ./skills/ (当前目录) | 最后加载，优先级最高 |

默认 WORKSPACE 为 ~/.goclaw/workspace。

1. 列出可用技能

   ./goclaw skills list
   

2. 安装技能 将技能文件夹放入以下任一位置：

   • ~/.goclaw/skills/ (用户全局目录)
   • ${WORKSPACE}/skills/ (工作区目录)
   • ./skills/ (当前目录，最高优先级，后加载会覆盖前面的)

3. 编写技能 创建一个目录 my-skill，并在其中创建 SKILL.md：

   ---
   name: my-skill
   description: A custom skill description.
   metadata:
     openclaw:
       requires:
         bins: ["python3"] # 仅当 python3 存在时加载
   ---
   # My Skill Instructions
   When the user asks for X, use `exec` to run `python3 script.py`.
   

项目结构

goclaw/
├── agent/              # Agent 核心逻辑
│   ├── loop.go         # Agent 循环
│   ├── context.go      # 上下文构建器
│   ├── memory.go       # 记忆系统
│   ├── skills.go       # 技能加载器
│   ├── subagent.go     # 子代理管理器
│   └── tools/          # 工具系统
│       ├── filesystem.go   # 文件系统工具
│       ├── shell.go        # Shell 工具
│       ├── web.go          # Web 工具
│       ├── browser.go      # 浏览器工具
│       └── message.go      # 消息工具
├── channels/           # 消息通道
│   ├── base.go         # 通道接口
│   ├── manager.go      # 通道管理器
│   ├── telegram.go     # Telegram 实现
│   ├── whatsapp.go     # WhatsApp 实现
│   ├── feishu.go       # 飞书实现
│   ├── qq.go           # QQ 实现
│   ├── wework.go       # 企业微信实现
│   ├── dingtalk.go     # 钉钉实现
│   ├── infoflow.go     # 百度如流实现
│   ├── gotify.go       # Gotify 实现
│   ├── slack.go        # Slack 实现
│   ├── discord.go      # Discord 实现
│   ├── googlechat.go   # Google Chat 实现
│   ├── teams.go        # Microsoft Teams 实现
│   └── weixin.go       # 微信实现
├── bus/                # 消息总线
│   ├── events.go       # 消息事件
│   └── queue.go        # 消息队列
├── config/             # 配置管理
│   ├── schema.go       # 配置结构
│   └── loader.go       # 配置加载器
├── providers/          # LLM 提供商
│   ├── base.go         # 提供商接口
│   ├── factory.go      # 提供商工厂
│   ├── openai.go       # OpenAI 实现
│   ├── anthropic.go    # Anthropic 实现
│   └── openrouter.go   # OpenRouter 实现
├── gateway/            # WebSocket 网关
│   ├── server.go       # 网关服务器
│   ├── handler.go      # 消息处理器
│   └── protocol.go     # 协议定义
├── cron/               # 定时任务调度
│   ├── scheduler.go    # 调度器
│   └── cron.go         # Cron 任务
├── session/            # 会话管理
│   └── manager.go      # 会话管理器
├── cli/                # 命令行界面
│   ├── root.go         # 根命令
│   ├── agent.go        # Agent 命令
│   ├── agents.go       # Agents 管理命令
│   ├── sessions.go     # 会话命令
│   ├── cron_cli.go     # Cron 命令
│   ├── approvals.go    # 审批命令
│   ├── system.go       # 系统命令
│   └── commands/       # 子命令
│       ├── tui.go      # TUI 命令
│       ├── gateway.go  # Gateway 命令
│       ├── browser.go  # Browser 命令
│       ├── health.go   # 健康检查
│       ├── status.go   # 状态查询
│       ├── memory.go   # 记忆管理
│       └── logs.go     # 日志查询
├── internal/           # 内部包
│   ├── logger/         # 日志
│   └── utils/          # 工具函数
├── docs/               # 文档
│   ├── cli.md          # CLI 详细文档
│   └── INTRODUCTION.md # 项目介绍
└── main.go             # 主入口

快速开始

安装

# 克隆仓库
git clone https://github.com/smallnest/goclaw.git
cd goclaw

# 安装依赖
go mod tidy

# 仅编译 Go 程序
go build -o goclaw .

# 完整构建（包含 UI，推荐）
make build-full

# 或直接运行
go run main.go start

本地可以访问 dashboard:

http://localhost:28789/dashboard/

配置

goclaw 按以下顺序查找配置文件（找到第一个即使用）：

1. ~/.goclaw/config.json (用户全局目录，最高优先级)
2. ./config.json (当前目录)
3. 环境变量 GOSKILLS_* 前缀

可通过 --config 参数指定配置文件路径覆盖默认行为。支持 YAML 和 JSON 格式。

创建 config.json (参考 internal/config.example.json):

{
  "workspace": {
    "path": ""
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "qianfan/kimi-k2.5"
      },
      "max_iterations": 15,
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "qianfan": {
        "baseUrl": "https://qianfan.baidubce.com/v2",
        "apiKey": "${QIANFAN_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "contextWindow": 131072,
            "maxTokens": 8192,
            "input": ["text", "image"]
          }
        ]
      },
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "contextWindow": 128000,
            "maxTokens": 16384,
            "input": ["text", "image"]
          }
        ]
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "token": "your-telegram-bot-token",
      "allowed_ids": []
    },
    "feishu": {
      "enabled": false,
      "app_id": "",
      "app_secret": "",
      "domain": "feishu",
      "group_policy": "open"
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "",
      "secret": "",
      "allowed_ids": []
    }
  },
  "tools": {
    "filesystem": {
      "allowed_paths": [],
      "denied_paths": []
    },
    "shell": {
      "enabled": true,
      "allowed_cmds": [],
      "denied_cmds": ["rm -rf", "dd", "mkfs", "format"],
      "timeout": 30,
      "working_dir": ""
    },
    "browser": {
      "enabled": true,
      "headless": true,
      "timeout": 30,
      "relay_url": "ws://127.0.0.1:18789",
      "relay_mode": "auto"
    }
  },
  "memory": {
    "backend": "builtin",
    "builtin": {
      "enabled": true,
      "database_path": "",
      "auto_index": true
    }
  }
}

运行

# 启动 Agent 服务
./goclaw start

# 交互式 TUI 模式
./goclaw tui

# 单次执行 Agent
./goclaw agent --message "你好，介绍一下你自己"

# 查看配置
./goclaw config show

# 查看帮助
./goclaw --help

启动 Dashboard

# 启动 WebSocket Gateway（内置 Dashboard UI）
./goclaw gateway run

# 访问 Dashboard
# 本地访问：http://localhost:28789/dashboard/
# 远程访问：http://your-host:28789/dashboard/?token=YOUR_TOKEN

Dashboard 功能：

• 实时聊天界面
• 会话管理
• Channel 状态监控
• Cron 任务管理

注意：如果监听非本地地址（非 127.0.0.1/localhost），远程访问需要配置 auth_token：

{
  "gateway": {
    "websocket": {
      "host": "0.0.0.0",
      "port": 28789,
      "enable_auth": true,
      "auth_token": "your-secret-token"
    }
  }
}

Desktop App (Tauri)

桌面版现在是一个本地壳程序：

• 启动时先拉起 sidecar goclaw start
• 等待 127.0.0.1:28789 就绪
• 自动在同一个窗口打开 http://127.0.0.1:28789/dashboard/
• 如果启动失败，会停留在本地启动页，并提供重启后端、打开配置文件的按钮

常用命令：

# 准备桌面版需要的 sidecar 和内嵌 dashboard 资源
make prepare-tauri-sidecar

# 开发模式运行桌面版
make dev-tauri

# 构建当前平台桌面版
make build-tauri-current

测试步骤：

# 1. 验证前端 dashboard 能正常构建
cd ui && npm run build

# 2. 验证 Tauri Rust 端能正常编译
cd ../src-tauri && cargo check

# 3. 验证桌面版 sidecar 资源准备完成
cd .. && make prepare-tauri-sidecar

# 4. 实际启动桌面版
make dev-tauri

启动后重点检查：

1. 首屏先出现本地启动页，而不是旧的 React 控制台壳。
2. 几秒内自动跳转到 http://127.0.0.1:28789/dashboard/。
3. Dashboard 中的 RPC 和 WebSocket 都能正常工作。
4. 关闭应用后，28789 端口不应残留由本应用启动的 sidecar 进程。
5. 如果故意把配置改坏，应用应停留在启动页，并能通过 “Restart Backend” 和 “Open Config” 恢复。

macOS 发布与公证流程见 docs/release-macos.md。

使用示例

# 查看所有可用命令
./goclaw --help

# 列出所有技能
./goclaw skills list

# 列出所有会话
./goclaw sessions list

# 查看 Gateway 状态
./goclaw gateway status

# 查看 Cron 任务
./goclaw cron list

# 健康检查
./goclaw health

CLI 命令参考

goclaw 提供了丰富的命令行工具，主要命令包括：

基本命令

| 命令 | 描述 | |-----|------| | goclaw start | 启动 Agent 服务 | | goclaw tui | 启动交互式终端界面 | | goclaw agent --message <msg> | 单次执行 Agent | | goclaw config show | 显示当前配置 |

Agent 管理