@clawmate/clawmate

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

发布

常用一键发布命令：

npm run release:patch
npm run release:minor
npm run release:major

也可以手动指定版本或先做预演：

npm run release -- 0.1.1 --publish
npm run release -- patch --dry-run

多 Agent 设计方案见 doc/multi-agent-design.md。

多 Agent 配置示例：

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

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

语音生成链路

当前语音不是简单的“把文本朗读出来”，而是由 Agent 基于角色人格和 TTS skill 判断，这一条回复是否更适合用短语音表达。

执行链路如下：

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>；成功时只发送语音，不重复发送同内容文字，失败时则降级为普通文字回复。

图像服务配置

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

服务特点与选型建议

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

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

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        # 安装向导

License

MIT