@clawmate/clawmate

v0.3.0

Published

7 days ago

One-click installer for the ClawMate OpenClaw companion plugin

0High
0Medium
0Low

byte-pioneer-ai

ClawMate

English | 中文

为 OpenClaw 添加一个有温度的角色伴侣。

她知道现在几点，知道你在做什么。你问她在哪，她就告诉你；你不问，她也可能随手发来一张自拍。

功能

时间感知 — 根据早晨、上课、午休、傍晚、深夜等时段自动切换场景与穿搭
情境生图 — 根据当前对话和状态生成角色自拍，支持写实与动漫风格
主动发图 — 支持配置触发频率，在日常聊天中随机发送自拍表达关心
语音交互 — 支持角色语音合成，在合适场景发送语音回复
多角色切换 — 每个角色拥有独立人设、时间状态与参考图，可一键切换
多 Agent 支持 — 多 Agent 场景下支持按 Agent 单独配置
自定义角色 — 通过对话创建新角色，由 LLM 引导生成完整角色定义并写入本地
多图像服务 — 支持阿里云百炼、火山引擎 ARK、fal.ai 和 OpenAI 兼容接口

应用场景

个人伴侣 — 日常陪伴、情感交流、生活助手
虚拟导师 — 学习辅导、知识答疑、进度跟踪
智能客服 — 企业服务、品牌形象、客户互动
专业顾问 — 健康管理、心理咨询、职业指导

开发计划

✅️ 更多角色 — 添加不同性格和背景的内置角色
✅️ 多 Agent 支持 — 多 Agent 场景下支持按 Agent 单独配置
✅️ 语音交互 — 角色语音合成，支持语音对话
[ ] 视频生成 — 短视频片段和动态表情
[ ] 社区角色 — 角色分享和下载平台

效果展示

对话界面

生成效果

更多样例图片见完整图片展示

快速开始

确保已安装 OpenClaw。

安装 / 更新

首次安装与后续更新使用同一命令：

npx @clawmate/clawmate

交互式安装向导会引导你完成角色选择、主动发图配置、语音配置和图像服务配置；多 Agent 场景下也支持只配置某个 Agent。

安装完成后，对你的 Agent 说：

发张自拍看看
你现在在干嘛？
晚上在卧室穿着粉色睡衣拍一张

创建自定义角色:

帮我创建一个[动漫/写实]风格的新角色，她是一个[描述职业/性格/背景]的女生

# 例：
帮我创建一个动漫风格的新角色，她是一个喜欢画画的大学生
帮我创建一个写实风格的新角色，她是一个热爱咖啡的独立书店店长

本地开发

git clone https://github.com/BytePioneer-AI/clawmate.git
cd clawmate
npm install
npm run clawmate:setup

多 Agent 配置示例：

{
  "selectedCharacter": "brooke-anime",
  "defaultProvider": "volcengine",
  "agents": {
    "ding-main": {
      "selectedCharacter": "brooke-anime",
      "defaultProvider": "volcengine"
    },
    "ding-work": {
      "selectedCharacter": "brooke",
      "defaultProvider": "aliyun"
    }
  }
}

插件会按当前 Agent 的 workspace 分别写入各自的 SOUL.md，不会再共用同一份人格文件。

图像服务配置

在 ~/.openclaw/openclaw.json 的 plugins.entries.clawmate-companion.config 下配置：

服务特点与选型建议

写实风格建议使用 Nano Banana。
除 Nano Banana 外，其他模型更建议搭配动漫角色。

| 服务 | 费用特性 | | --- | --- | | Gemini 官方 SDK | 取决于 Gemini API 或代理服务额度 | | ModelScope | 完全免费 | | 阿里云百炼 | 有免费额度（以官方控制台为准） | | 火山引擎 ARK | 有免费额度（以官方控制台为准） | | OpenAI 兼容接口 | 取决于接入服务商 | | fal.ai | 取决于平台计费策略 |

Gemini 官方 SDK（官方默认地址）

{
  "defaultProvider": "gemini",
  "providers": {
    "gemini": {
      "type": "gemini",
      "apiKey": "YOUR_GEMINI_API_KEY",
      "model": "gemini-3.1-flash-image-preview"
    }
  }
}

Gemini 官方 SDK（自定义 BaseURL）

{
  "defaultProvider": "gemini",
  "providers": {
    "gemini": {
      "type": "gemini",
      "apiKey": "YOUR_GEMINI_API_KEY",
      "baseUrl": "https://your-proxy.example.com",
      "model": "gemini-3.1-flash-image-preview"
    }
  }
}

Gemini provider 走 Google GenAI SDK 原生图片请求，不复用 OpenAI-compatible 适配层。

baseUrl 为空或不写时，使用 Gemini SDK 官方默认 API 地址
baseUrl 有值时，改走你提供的自定义地址
自定义 baseUrl 需要兼容 Google GenAI SDK 的请求路径和鉴权语义
有参考图时会把参考图作为 inline image part 一起发给 Gemini

CLI 当前内置以下 Gemini 预设模型，也支持手动输入自定义模型名：

gemini-3-pro-image-preview
gemini-3.1-flash-image-preview
gemini-2.5-flash-image
gemini-2.5-flash-image-preview

OpenAI 兼容接口

{
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "name": "openai",
      "apiKey": "YOUR_OPENAI_API_KEY",
      "baseUrl": "https://api.openai.com/v1",
      "model": "gpt-image-1.5"
    }
  }
}

支持兼容 OpenAI 的图片模型服务，可通过 baseUrl 指定自定义端点。有输入图片时优先尝试 /v1/images/edits，失败后回退到 /v1/chat/completions；没有输入图片时直接调用 /v1/chat/completions。

阿里云百炼

{
  "defaultProvider": "aliyun",
  "providers": {
    "aliyun": {
      "apiKey": "YOUR_DASHSCOPE_API_KEY",
      "model": "wan2.6-image"
    }
  }
}

火山引擎 ARK（API申请文档）

{
  "defaultProvider": "volcengine",
  "providers": {
    "volcengine": {
      "apiKey": "YOUR_ARK_API_KEY",
      "model": "doubao-seedream-4-5-251128"
    }
  }
}

fal.ai

{
  "defaultProvider": "fal",
  "providers": {
    "fal": {
      "apiKey": "YOUR_FAL_KEY",
      "model": "fal-ai/flux/dev/image-to-image"
    }
  }
}

主动发图

{
  "proactiveSelfie": {
    "enabled": true,
    "probability": 0.1
  }
}

probability 为每条消息的触发概率，推荐范围 0.1–0.3。

多角色

内置角色

在 assets/characters/ 下新建角色目录，包含：

{character-id}/
├── meta.json           # id、name、style（photorealistic/anime）、timeStates
├── character-prompt.md # 角色人设（英文）
├── README.md           # 角色档案（中文）
├── images/             # 参考图文件夹
│   └── reference.png
└── *.png               # 其他参考图（可选）

然后在配置中切换：

{
  "selectedCharacter": "your-character-id"
}

自定义角色（对话创建）

直接对 Agent 说：

帮我创建一个新角色，她是一个喜欢画画的大学生

Agent 会调用 clawmate_prepare_character 获取角色定义模板和样例，引导你补充细节，然后调用 clawmate_create_character 将角色写入 ~/.openclaw/clawmeta/。

自定义角色目录与内置角色分离，加载时用户目录优先。也可以通过配置 userCharacterRoot 自定义存储路径。

项目结构

ClawMate/
└── packages/clawmate-companion/
    ├── src/core/          # 核心逻辑（pipeline、router、providers）
    ├── skills/            # Skill 定义与角色素材
    │   └── clawmate-companion/
    │       ├── SKILL.md
    │       └── assets/characters/
    │           └── brooke/
    └── bin/cli.cjs        # 安装向导

语音生成链路

执行链路如下：

Agent 判断 -> Tool 合成 -> 插件落盘 -> 返回 MEDIA

before_agent_start 会注入角色 SOUL.md；启用 TTS 时，还会追加一条轻量提示，让 Agent 在合适的时候使用 clawmate-companion-tts skill。
Agent 结合角色 prompt 和 TTS skill 判断当前回复是否适合发语音；如果适合，会生成一段适合口播的短文本，并调用 clawmate_generate_tts。
clawmate_generate_tts 会调用阿里云千问 TTS 的 DashScope 原生接口进行合成，当前默认模型为 qwen3-tts-flash，默认音色为 Chelsie。
插件收到远端音频地址后，会将音频下载到本地 ~/.openclaw/media/clawmate-voice/YYYY-MM-DD/。
Tool 最终返回 MEDIA: <audioPath>；成功时只发送语音，不重复发送同内容文字，失败时则降级为普通文字回复。

License

MIT