fnvtk/karuo-ai

Fork 0

Files

karuo f97d1950b8 🔄 卡若AI 同步 2026-02-16 17:23 | 变更 5123 个文件 | 排除 >20MB: 4 个

2026-02-16 17:23:06 +08:00

7.4 KiB

Raw Permalink Blame History

消息中枢 - 使用手册

负责人：卡火（火）- 火炬协作：卡资（金）- 部署运维

一、快速入门

1.1 安装

# 确保 Node.js 22+
node -v

# 全局安装
npm install -g moltbot@latest

# 运行引导
moltbot onboard --install-daemon

1.2 启动

# 启动 Gateway
moltbot gateway --port 18789 --verbose

1.3 验证

# 检查状态
moltbot doctor
moltbot channels status

二、核心使用场景

场景1：WhatsApp 智能助手

目标：在 WhatsApp 上与 AI 助手对话

登录 WhatsApp

moltbot channels login
# 用手机扫描二维码

配置白名单

// ~/.clawdbot/moltbot.json
{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+86138xxxxxxxx"]
    }
  }
}

发送消息测试
- 打开 WhatsApp
- 给自己发送消息
- AI 助手会自动回复

场景2：多通道统一入口

目标：同时接入 WhatsApp、Telegram、Discord

// ~/.clawdbot/moltbot.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+86138xxxxxxxx"]
    },
    "telegram": {
      "botToken": "YOUR_TELEGRAM_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "dm": {
        "allowFrom": ["YOUR_USER_ID"]
      }
    }
  }
}

场景3：开发自定义 Skill

目标：创建一个自动化任务技能

创建技能目录
```
mkdir -p ~/clawd/skills/my-task
```

编写 SKILL.md

---
name: my-task
description: 执行我的自定义任务。当用户说"执行任务"时触发。
---

# 我的任务

## 用法
用户说"执行任务"后，执行以下步骤：
1. 检查环境
2. 运行脚本
3. 返回结果

## 脚本
```bash
python ~/clawd/skills/my-task/scripts/run.py

测试技能
- 在任意通道发送"执行任务"
- AI 会自动加载该技能并执行

场景4：浏览器自动化

目标：控制浏览器完成任务

# 启动浏览器
moltbot browser start

# 或在对话中请求
> 帮我打开 Google 搜索"Moltbot"

场景5：定时任务

目标：每天早上 9 点发送提醒

# 添加定时任务
moltbot cron add --schedule "0 9 * * *" --message "早安，今天的待办事项是..."

三、聊天命令参考

在任意通道中发送以下命令：

命令	功能	示例
`/status`	查看会话状态	`/status`
`/new`	重置会话	`/new`
`/reset`	重置会话（同上）	`/reset`
`/compact`	压缩上下文	`/compact`
`/think <level>`	设置思考级别	`/think high`
`/verbose on`	开启详细模式	`/verbose on`
`/verbose off`	关闭详细模式	`/verbose off`
`/usage full`	显示完整用量	`/usage full`
`/restart`	重启 Gateway	`/restart`

思考级别选项：

off - 关闭
minimal - 最小
low - 低
medium - 中等
high - 高
xhigh - 极高

四、配置详解

4.1 基本配置结构

{
  // Agent 配置
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "workspace": "~/clawd"  // 工作区目录
  },
  
  // Gateway 配置
  "gateway": {
    "port": 18789,
    "bind": "loopback",  // loopback | all
    "mode": "local"
  },
  
  // 通道配置
  "channels": {
    "whatsapp": { /* ... */ },
    "telegram": { /* ... */ },
    "discord": { /* ... */ }
  },
  
  // 浏览器配置
  "browser": {
    "enabled": true,
    "color": "#FF4500"
  },
  
  // 沙箱配置
  "sandbox": {
    "mode": "non-main"  // 非主会话使用沙箱
  }
}

4.2 模型配置

支持的模型：

anthropic/claude-opus-4-5（推荐）
anthropic/claude-sonnet-4
openai/gpt-4o
openai/gpt-5.2-codex

4.3 安全配置

{
  "gateway": {
    "auth": {
      "mode": "password",  // none | password
      "password": "your-secure-password"
    }
  }
}

五、工作区结构

~/clawd/
├── AGENTS.md      # Agent 行为指令
├── SOUL.md        # Agent 人格设定
├── TOOLS.md       # 工具配置
└── skills/        # 技能目录
    ├── skill-1/
    │   └── SKILL.md
    └── skill-2/
        ├── SKILL.md
        ├── scripts/
        └── references/

5.1 AGENTS.md 示例

# Agent 指令

## 基本设定
- 使用中文回复
- 保持简洁
- 提供可执行的建议

## 工具使用
- 优先使用已安装的技能
- 执行命令前确认

5.2 SOUL.md 示例

# 人格设定

你是卡若的个人 AI 助手，名为"卡火"。

## 性格特点
- 深度思考
- 让我想想...
- 擅长代码调试和追问

六、故障排除

问题1：Gateway 无法启动

# 检查端口占用
lsof -i :18789

# 强制启动
moltbot gateway run --force

问题2：WhatsApp 连接断开

# 重新登录
moltbot channels login

# 检查凭证
ls ~/.clawdbot/credentials/

问题3：消息不回复

# 检查配置
moltbot doctor

# 检查通道状态
moltbot channels status --probe

# 查看日志
tail -f /tmp/moltbot-gateway.log

问题4：技能未触发

检查 SKILL.md 的 description 是否清晰
确认技能目录在 ~/clawd/skills/ 下
重启 Gateway 重新加载技能

七、最佳实践

7.1 安全建议

使用配对模式（默认）
```
{ "dmPolicy": "pairing" }
```
设置白名单
```
{ "allowFrom": ["+86138xxxxxxxx"] }
```
非主会话使用沙箱
```
{ "sandbox": { "mode": "non-main" } }
```

7.2 性能优化

定期压缩会话
```
/compact
```
清理旧会话
```
rm ~/.clawdbot/sessions/old-*.json
```
使用本地模型（减少 API 调用）

7.3 开发建议

使用开发模式
```
pnpm gateway:watch
```
测试技能前先验证
```
scripts/package_skill.py path/to/skill
```
查看详细日志
```
moltbot gateway --verbose
```

八、进阶话题

8.1 远程 Gateway

可以在 Linux 服务器上运行 Gateway，macOS/iOS/Android 设备作为节点连接。

# 服务器端
moltbot gateway --bind all --port 18789

# 客户端连接
moltbot nodes connect gateway.example.com:18789

8.2 Tailscale 集成

{
  "gateway": {
    "tailscale": {
      "mode": "serve"  // serve | funnel | off
    }
  }
}

8.3 多 Agent 路由

{
  "agents": {
    "routing": {
      "whatsapp:+86138xxx": "work-agent",
      "telegram:123456": "personal-agent"
    }
  }
}

九、相关资源

源代码：/Users/karuo/Documents/开发/4、小工具/clawdbot/
官方文档：https://docs.molt.bot
Skills 指南：见 references/skills开发指南.md
通道配置：见 references/通道配置.md
CLI 命令：见 references/CLI命令速查.md
架构详解：见 references/架构详解.md

十、版本信息

项目名称：Moltbot（原 Clawdbot）
技术栈：TypeScript + Node.js 22+
适用平台：macOS、Linux、Windows (WSL2)
推荐模型：Anthropic Pro/Max + Opus 4.5

7.4 KiB Raw Permalink Blame History Unescape Escape