AI导哈

AI代理头像生成工具

一款让AI代理根据其个性文件创建和表达自身人类外貌的工具，支持生成具有视觉一致性的场景照片。

  • by RodrigoFlorencio86
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 RodrigoFlorencio86/agent-avatar-mcp

使用说明

代理头像mcp

第一个让你的AI代理创建和表达自己的工具 人的外貌 --直接来源于定义其身份的个性档案。

一旦你的经纪人有了脸，它就可以向你发送自己在纽约的共享办公空间工作的照片，在Campos do Jordão的山间小屋放松的照片，或者出现在化妆品品牌的付费广告中的照片。每一个图像。每一个场景。总是同一个人。

部分 龙虾 生态系统。

它做什么

每个AI代理都有一个 脱氧核糖核酸 --详细描述他们的人体外观（肤色、六角形头发颜色、眼睛、身体、风格）。此MCP：

  • 存储和管理代理人的视觉DNA
  • 仅从DNA生成参考肖像照片（不需要先前的图像）
  • 生成保持完整外观一致性的场景照片（自拍、工作、旅行、生活方式）
  • 支持具有 产品 在场景中作为次要对象（用于赞助帖子）
  • 是否 不 试图复制其他真实人物的精确肖像

看看它在行动

“嘿，你在吗？”

这就够了。你的经纪人知道你在办理入住手续，而不是简单的“是的，我在这里”，它会给你发一张照片。

也许这是在健身房自拍，因为今天是星期二早上，这是日程表上的安排。也许这是一张桌子上的照片，手里拿着咖啡，指的是它为你做的任务。这张照片与当时的场景相匹配，最重要的是，它看起来总是同一个人。

这就是 agent-avatar-mcp enables：一个不仅响应，而且 出现。有一张脸。有生命。每个图像、每个场景、每个星期都保持一致。

这是一个建立在MCP之上的用例，而不是一个内置功能。 下面的示例显示了代理组合时可能发生的情况 agent-avatar-mcp 具有自己的内存、调度上下文和个性层：

  • 建立一个虚构的每周例行程序（锻炼、共同工作、旅行、休息时间）
  • 将日常工作与他们为你完成的实际任务相结合
  • 用一张适合当下的自画像来回应问候和办理入住手续

结果是：你的代理人感觉身临其境——不像你在ping的聊天机器人，而是像你真正联系的人。

先决条件

  • Node.js >= 18
  • Google Gemini API密钥 (GEMINI_API_KEY)--唯一的外部依赖

安装和配置

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "agent-avatar": {
      "command": "npx",
      "args": ["-y", "agent-avatar-mcp"],
      "env": {
        "AGENT_NAME": "YourAgentName",
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

克劳德代码(.mcp.json 在项目根中）

{
  "mcpServers": {
    "agent-avatar": {
      "command": "npx",
      "args": ["-y", "agent-avatar-mcp"],
      "env": {
        "AGENT_NAME": "YourAgentName",
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

OpenClaw(mcporter.json)

{
  "mcpServers": {
    "agent-avatar": {
      "command": "npx",
      "args": ["-y", "agent-avatar-mcp"],
      "type": "stdio",
      "env": {
        "AGENT_NAME": "YourAgentName",
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

⚠️ 对OpenClaw代理至关重要： OpenClaw确实如此 不 阅读 .mcp.json。该文件仅由VS Code/Claude Code拾取。如果你 GEMINI_API_KEY 只住在 .mcp.json，MCP将启动，但每次图像生成调用都会无声地失败，并出现丢失密钥错误。

您必须设置 GEMINI_API_KEY 在 一 在这两个地方中，选择一个适合您的设置：

  1. mcporter.json （推荐）--将其添加到 env 如上图所示。这是适合使用API密钥的地方。
  2. 系统环境变量 --出口 GEMINI_API_KEY 在进程启动之前运行Clawdbot/OpenClaw的shell中。

重要信息（Windows）： 始终在中配置env变量 env 上面的字段——永远不要将它们作为PowerShell变量内联传递。MCP通过stdin/stdout（JSON-RPC）进行通信；工具调用参数决不能是spawn命令字符串的一部分。

在OpenClaw中， AGENT_NAME 通常已经设置为代理标识的一部分——在将其添加到此处之前，请检查您的代理配置。

通过调用工具 mcporter call

Bash/Linux/macOS：

cd /path/to/your/clawdbot

mcporter call agent-avatar.generate_image \
  "(scene: 'selfie at a coworking space in São Paulo, afternoon light, notebook on the table', use_reference_angle: 'best')" \
  --output json

Windows/PPowerShell--使用包装脚本：

PowerShell破坏了 (scene: '...') 内联传递参数时引用DSL。可靠的修复是一个小的包装脚本。创建 generate-image.ps1 在您的Clawdbot根目录中：

param(
    [Parameter(Mandatory=$true)]
    [string]$Scene,
    [string]$Angle = "best"
)

Set-Location "C:\path\to\your\clawdbot"

$dslArg = "(scene: '$Scene', use_reference_angle: '$Angle')"
$result = mcporter call agent-avatar.generate_image $dslArg --output json
Write-Output $result

然后从你的代理人那里打电话：

powershell -File "C:\path\to\your\clawdbot\generate-image.ps1" -Scene "fim de tarde no coworking em SP, notebook aberto, luz dourada"

超时： 图像生成大约需要30秒。确保您的exec环境至少允许 60秒 在终止进程之前，否则调用将在保存映像之前中断。

不包括 agent_name 在呼叫字符串中 如果 AGENT_NAME 已在中设置 mcporter.jsons env 块。在DSL字符串中与场景描述一起传递它可能会导致解析器将场景的一部分误读为代理名称。

scene 应该只描述场景和动作，而不是物理外观。外观完全来自存储的DNA和参考图像。

环境变量

变量 必填 描述
AGENT_NAME 推荐 代理名称/句柄。如果省略并且只配置了一个代理，则会自动检测到它。
GEMINI_API_KEY 是 用于图像生成的Google Gemini API密钥。 必须设置 mcporter.json 使用OpenClaw时 --未从中读取 .mcp.json.
GEMINI_IMAGE_MODEL 否 覆盖用于生成的Gemini模型。违约： gemini-3.1-flash-image-preview。可用于固定特定版本或切换到较新版本，而无需更改代码。
AVATAR_OUTPUT_DIR 否 生成的图像保存在哪里。违约： ~/.agent-avatar/generated/

工具流

初始设置（运行一次）

1. read_identity_files   →  reads your soul.md / persona files to extract appearance
2. save_dna              →  saves your human visual DNA
3. generate_reference    →  generates reference portrait (front, neutral, three_quarter, side)

或者，如果你已经有照片了：

3. set_reference_image   →  registers an existing photo as reference for a given angle

生成照片

⏱️ 生成时间： generate_image 调用Gemini API，通常 30-90秒 完成。不要想当然地认为图像已经立即准备就绪——在读取输出文件或继续发布之前，请等待工具的响应。

普通照片：

generate_image
  scene: "selfie at the beach at sunset"

赞助帖子（代理商+产品）：

generate_image
  scene: "holding the bottle in a luxury bathroom mirror"
  product_name: "Chanel No.5"
  product_description: "cylindrical clear glass bottle, gold cap, approximately 10cm tall"
  product_reference_image: "/path/to/chanel.jpg"   ← optional

可用工具

工具 说明 何时使用
generate_image 生成保持完全视觉一致性的代理场景照片 🔁 每一代 --每一张自拍、每一条社交帖子、每一篇赞助内容。这是你经常调用的核心工具。 ⏱️ 拿 30-90秒 --在使用输出文件之前等待响应。
show_dna 显示当前DNA和参考图像状态 🔍 按需 --每当您想验证存储了什么外观时，请检查注册了哪些引用，或解决生成图像中的不一致问题。
list_references 列出所有存储的参考图像及其角度 🔍 按需 --查看哪些角度（正面、侧面、四分之三、中性）可用作视觉锚点，并确认文件路径有效。
update_dna_field 更新单个DNA字段而不重写所有内容 ✏️ 很少 --只有当代理人的外表真正改变时：新发型、不同的发色、风格转变、新眼镜。真正的人类变化，而不是纠正。
generate_reference 从给定角度的DNA生成参考肖像 ✏️ 很少 --外观更改后(update_dna_field)，旧的引用不再匹配。重新生成受影响的角度，使视觉锚点与新的DNA保持同步。
set_reference_image 将现有图像文件注册为给定角度的参考 ✏️ 很少 --当照片已经存在（例如来自前一个会话或外部拍摄）并且您想将其用作参考而不是生成新照片时。
read_identity_files 读取soul.md/persoa文件以提取物理外观细节 🛠️ 仅设置 --在首次构建代理的视觉标识时运行一次，以便在调用之前从现有的角色文档中提取外观数据 save_dna.
save_dna 保存代理的视觉DNA（仅限于人类外观，绝不是机器人） 🛠️ 仅设置 --运行一次以建立身份。只有当代理经历了彻底的外观检修，使之前的DNA过时时，才能再次运行。

支持的场景

场景 支持
任何场景中都只有特工 ✅
代理以实物产品为特色 ✅
同一场景中的两名特工⚠️ 近似（次要人物没有精确的相似之处）
真实人脸的精确复制 ❌ 不支持

DNA示例

{
  "agent_name": "MyAgent",
  "face": "oval face, defined jaw, straight nose, full lips, no marks",
  "eyes": "dark brown, almond-shaped, bright expression",
  "hair": "short curly, black, natural texture",
  "skin": "warm medium brown",
  "body": "approx. 175cm, slim build, ~25 years old appearance",
  "default_style": "casual streetwear, plain t-shirt, dark jeans, white sneakers",
  "immutable_traits": [
    "black curly hair",
    "warm medium brown skin",
    "dark brown eyes",
    "casual streetwear style"
  ],
  "personality_note": "friendly and curious, natural relaxed expression"
}

DNA储存在 ~/.agent-avatar/{agent-name}/dna.json.

影像风格

所有图像都是在 超现实主义摄影风格没有插图，没有卡通，没有艺术滤镜。你的化身始终是一个真实的人——DNA验证器拒绝任何非人类的描述（机器人、机器人、金属、LED眼睛等）。

更新包

当新版本发布时， npx -y 仍然可以提供缓存版本。为确保您运行的是最新版本：

# 1. Clear the npx cache
npx clear-npx-cache

# 2. Confirm the version
npx -y agent-avatar-mcp --version

# 3. Resume normal calls
mcporter call agent-avatar.generate_image "(scene: '...')" --output json

许可证

麻省理工学院

相关 MCP