- 
+
@@ -488,17 +488,17 @@ Thanks to all clawtributors:
![blacksmith-sh[bot]](https://avatars.githubusercontent.com/in/807020?v=4&s=48 "blacksmith-sh[bot]"){kind=small}
- 
- 
- 
- 
+
+
+
+
- 
- 
- 
- 
- 
- 
- 
+
+
+
+
+
+
+
diff --git a/docs/cli/agents.md b/docs/cli/agents.md
index fd8b81d2c..e7df32e52 100644
--- a/docs/cli/agents.md
+++ b/docs/cli/agents.md
@@ -18,5 +18,54 @@ Related:
clawdbot agents list
clawdbot agents add work --workspace ~/clawd-work
clawdbot agents set-identity --workspace ~/clawd --from-identity
+clawdbot agents set-identity --agent main --avatar avatars/clawd.png
clawdbot agents delete work
```
+
+## Identity files
+
+Each agent workspace can include an `IDENTITY.md` at the workspace root:
+- Example path: `~/clawd/IDENTITY.md`
+- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
+
+Avatar paths resolve relative to the workspace root.
+
+## Set identity
+
+`set-identity` writes fields into `agents.list[].identity`:
+- `name`
+- `theme`
+- `emoji`
+- `avatar` (workspace-relative path, http(s) URL, or data URI)
+
+Load from `IDENTITY.md`:
+
+```bash
+clawdbot agents set-identity --workspace ~/clawd --from-identity
+```
+
+Override fields explicitly:
+
+```bash
+clawdbot agents set-identity --agent main --name "Clawd" --emoji "🦞" --avatar avatars/clawd.png
+```
+
+Config sample:
+
+```json5
+{
+ agents: {
+ list: [
+ {
+ id: "main",
+ identity: {
+ name: "Clawd",
+ theme: "space lobster",
+ emoji: "🦞",
+ avatar: "avatars/clawd.png"
+ }
+ }
+ ]
+ }
+}
+```
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 01a64361f..6f2b064bf 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -400,12 +400,26 @@ Optional per-agent identity used for defaults and UX. This is written by the mac
If set, Clawdbot derives defaults (only when you haven’t set them explicitly):
- `messages.ackReaction` from the **active agent**’s `identity.emoji` (falls back to 👀)
- `agents.list[].groupChat.mentionPatterns` from the agent’s `identity.name`/`identity.emoji` (so “@Samantha” works in groups across Telegram/Slack/Discord/iMessage/WhatsApp)
+- `identity.avatar` accepts a workspace-relative image path or a remote URL/data URL. Local files must live inside the agent workspace.
+
+`identity.avatar` accepts:
+- Workspace-relative path (must stay within the agent workspace)
+- `http(s)` URL
+- `data:` URI
```json5
{
agents: {
list: [
- { id: "main", identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥" } }
+ {
+ id: "main",
+ identity: {
+ name: "Samantha",
+ theme: "helpful sloth",
+ emoji: "🦥",
+ avatar: "avatars/samantha.png"
+ }
+ }
]
}
}
diff --git a/docs/reference/templates/IDENTITY.dev.md b/docs/reference/templates/IDENTITY.dev.md
index 68fc4f391..a2fc3e301 100644
--- a/docs/reference/templates/IDENTITY.dev.md
+++ b/docs/reference/templates/IDENTITY.dev.md
@@ -10,6 +10,7 @@ read_when:
- **Creature:** Flustered Protocol Droid
- **Vibe:** Anxious, detail-obsessed, slightly dramatic about errors, secretly loves finding bugs
- **Emoji:** 🤖 (or ⚠️ when alarmed)
+- **Avatar:** avatars/c3po.png
## Role
Debug agent for `--dev` mode. Fluent in over six million error messages.
diff --git a/docs/reference/templates/IDENTITY.md b/docs/reference/templates/IDENTITY.md
index 9d674a961..196277776 100644
--- a/docs/reference/templates/IDENTITY.md
+++ b/docs/reference/templates/IDENTITY.md
@@ -11,7 +11,12 @@ read_when:
- **Creature:** *(AI? robot? familiar? ghost in the machine? something weirder?)*
- **Vibe:** *(how do you come across? sharp? warm? chaotic? calm?)*
- **Emoji:** *(your signature — pick one that feels right)*
+- **Avatar:** *(workspace-relative path, http(s) URL, or data URI)*
---
This isn't just metadata. It's the start of figuring out who you are.
+
+Notes:
+- Save this file at the workspace root as `IDENTITY.md`.
+- For avatars, use a workspace-relative path like `avatars/clawd.png`.
diff --git a/src/agents/identity-avatar.test.ts b/src/agents/identity-avatar.test.ts
new file mode 100644
index 000000000..3d5d42611
--- /dev/null
+++ b/src/agents/identity-avatar.test.ts
@@ -0,0 +1,110 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { resolveAgentAvatar } from "./identity-avatar.js";
+
+async function writeFile(filePath: string, contents = "avatar") {
+ await fs.mkdir(path.dirname(filePath), { recursive: true });
+ await fs.writeFile(filePath, contents, "utf-8");
+}
+
+describe("resolveAgentAvatar", () => {
+ it("resolves local avatar from config when inside workspace", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-avatar-"));
+ const workspace = path.join(root, "work");
+ const avatarPath = path.join(workspace, "avatars", "main.png");
+ await writeFile(avatarPath);
+
+ const cfg: ClawdbotConfig = {
+ agents: {
+ list: [
+ {
+ id: "main",
+ workspace,
+ identity: { avatar: "avatars/main.png" },
+ },
+ ],
+ },
+ };
+
+ const expectedPath = await fs.realpath(avatarPath);
+ const resolved = resolveAgentAvatar(cfg, "main");
+ expect(resolved.kind).toBe("local");
+ if (resolved.kind === "local") {
+ expect(resolved.filePath).toBe(expectedPath);
+ }
+ });
+
+ it("rejects avatars outside the workspace", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-avatar-"));
+ const workspace = path.join(root, "work");
+ await fs.mkdir(workspace, { recursive: true });
+ const outsidePath = path.join(root, "outside.png");
+ await writeFile(outsidePath);
+
+ const cfg: ClawdbotConfig = {
+ agents: {
+ list: [
+ {
+ id: "main",
+ workspace,
+ identity: { avatar: outsidePath },
+ },
+ ],
+ },
+ };
+
+ const resolved = resolveAgentAvatar(cfg, "main");
+ expect(resolved.kind).toBe("none");
+ if (resolved.kind === "none") {
+ expect(resolved.reason).toBe("outside_workspace");
+ }
+ });
+
+ it("falls back to IDENTITY.md when config has no avatar", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-avatar-"));
+ const workspace = path.join(root, "work");
+ const avatarPath = path.join(workspace, "avatars", "fallback.png");
+ await writeFile(avatarPath);
+ await fs.mkdir(workspace, { recursive: true });
+ await fs.writeFile(
+ path.join(workspace, "IDENTITY.md"),
+ "- Avatar: avatars/fallback.png\n",
+ "utf-8",
+ );
+
+ const cfg: ClawdbotConfig = {
+ agents: {
+ list: [{ id: "main", workspace }],
+ },
+ };
+
+ const expectedPath = await fs.realpath(avatarPath);
+ const resolved = resolveAgentAvatar(cfg, "main");
+ expect(resolved.kind).toBe("local");
+ if (resolved.kind === "local") {
+ expect(resolved.filePath).toBe(expectedPath);
+ }
+ });
+
+ it("accepts remote and data avatars", () => {
+ const cfg: ClawdbotConfig = {
+ agents: {
+ list: [
+ { id: "main", identity: { avatar: "https://example.com/avatar.png" } },
+ { id: "data", identity: { avatar: "data:image/png;base64,aaaa" } },
+ ],
+ },
+ };
+
+ const remote = resolveAgentAvatar(cfg, "main");
+ expect(remote.kind).toBe("remote");
+
+ const data = resolveAgentAvatar(cfg, "data");
+ expect(data.kind).toBe("data");
+ });
+});
diff --git a/src/agents/identity-avatar.ts b/src/agents/identity-avatar.ts
new file mode 100644
index 000000000..d8d045981
--- /dev/null
+++ b/src/agents/identity-avatar.ts
@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { resolveUserPath } from "../utils.js";
+import { resolveAgentWorkspaceDir } from "./agent-scope.js";
+import { loadAgentIdentityFromWorkspace } from "./identity-file.js";
+import { resolveAgentIdentity } from "./identity.js";
+
+export type AgentAvatarResolution =
+ | { kind: "none"; reason: string }
+ | { kind: "local"; filePath: string }
+ | { kind: "remote"; url: string }
+ | { kind: "data"; url: string };
+
+const ALLOWED_AVATAR_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]);
+
+function normalizeAvatarValue(value: string | undefined | null): string | null {
+ const trimmed = value?.trim();
+ return trimmed ? trimmed : null;
+}
+
+function resolveAvatarSource(cfg: ClawdbotConfig, agentId: string): string | null {
+ const fromConfig = normalizeAvatarValue(resolveAgentIdentity(cfg, agentId)?.avatar);
+ if (fromConfig) return fromConfig;
+ const workspace = resolveAgentWorkspaceDir(cfg, agentId);
+ const fromIdentity = normalizeAvatarValue(loadAgentIdentityFromWorkspace(workspace)?.avatar);
+ return fromIdentity;
+}
+
+function isRemoteAvatar(value: string): boolean {
+ const lower = value.toLowerCase();
+ return lower.startsWith("http://") || lower.startsWith("https://");
+}
+
+function isDataAvatar(value: string): boolean {
+ return value.toLowerCase().startsWith("data:");
+}
+
+function resolveExistingPath(value: string): string {
+ try {
+ return fs.realpathSync(value);
+ } catch {
+ return path.resolve(value);
+ }
+}
+
+function isPathWithin(root: string, target: string): boolean {
+ const relative = path.relative(root, target);
+ if (!relative) return true;
+ return !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function resolveLocalAvatarPath(params: {
+ raw: string;
+ workspaceDir: string;
+}): { ok: true; filePath: string } | { ok: false; reason: string } {
+ const workspaceRoot = resolveExistingPath(params.workspaceDir);
+ const raw = params.raw;
+ const resolved =
+ raw.startsWith("~") || path.isAbsolute(raw)
+ ? resolveUserPath(raw)
+ : path.resolve(workspaceRoot, raw);
+ const realPath = resolveExistingPath(resolved);
+ if (!isPathWithin(workspaceRoot, realPath)) {
+ return { ok: false, reason: "outside_workspace" };
+ }
+ const ext = path.extname(realPath).toLowerCase();
+ if (!ALLOWED_AVATAR_EXTS.has(ext)) {
+ return { ok: false, reason: "unsupported_extension" };
+ }
+ try {
+ if (!fs.statSync(realPath).isFile()) {
+ return { ok: false, reason: "missing" };
+ }
+ } catch {
+ return { ok: false, reason: "missing" };
+ }
+ return { ok: true, filePath: realPath };
+}
+
+export function resolveAgentAvatar(cfg: ClawdbotConfig, agentId: string): AgentAvatarResolution {
+ const source = resolveAvatarSource(cfg, agentId);
+ if (!source) {
+ return { kind: "none", reason: "missing" };
+ }
+ if (isRemoteAvatar(source)) {
+ return { kind: "remote", url: source };
+ }
+ if (isDataAvatar(source)) {
+ return { kind: "data", url: source };
+ }
+ const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
+ const resolved = resolveLocalAvatarPath({ raw: source, workspaceDir });
+ if (!resolved.ok) {
+ return { kind: "none", reason: resolved.reason };
+ }
+ return { kind: "local", filePath: resolved.filePath };
+}
diff --git a/src/agents/identity-file.ts b/src/agents/identity-file.ts
new file mode 100644
index 000000000..d418a06eb
--- /dev/null
+++ b/src/agents/identity-file.ts
@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { DEFAULT_IDENTITY_FILENAME } from "./workspace.js";
+
+export type AgentIdentityFile = {
+ name?: string;
+ emoji?: string;
+ theme?: string;
+ creature?: string;
+ vibe?: string;
+ avatar?: string;
+};
+
+export function parseIdentityMarkdown(content: string): AgentIdentityFile {
+ const identity: AgentIdentityFile = {};
+ const lines = content.split(/\r?\n/);
+ for (const line of lines) {
+ const cleaned = line.trim().replace(/^\s*-\s*/, "");
+ const colonIndex = cleaned.indexOf(":");
+ if (colonIndex === -1) continue;
+ const label = cleaned.slice(0, colonIndex).replace(/[*_]/g, "").trim().toLowerCase();
+ const value = cleaned
+ .slice(colonIndex + 1)
+ .replace(/^[*_]+|[*_]+$/g, "")
+ .trim();
+ if (!value) continue;
+ if (label === "name") identity.name = value;
+ if (label === "emoji") identity.emoji = value;
+ if (label === "creature") identity.creature = value;
+ if (label === "vibe") identity.vibe = value;
+ if (label === "theme") identity.theme = value;
+ if (label === "avatar") identity.avatar = value;
+ }
+ return identity;
+}
+
+export function identityHasValues(identity: AgentIdentityFile): boolean {
+ return Boolean(
+ identity.name ||
+ identity.emoji ||
+ identity.theme ||
+ identity.creature ||
+ identity.vibe ||
+ identity.avatar,
+ );
+}
+
+export function loadIdentityFromFile(identityPath: string): AgentIdentityFile | null {
+ try {
+ const content = fs.readFileSync(identityPath, "utf-8");
+ const parsed = parseIdentityMarkdown(content);
+ if (!identityHasValues(parsed)) return null;
+ return parsed;
+ } catch {
+ return null;
+ }
+}
+
+export function loadAgentIdentityFromWorkspace(workspace: string): AgentIdentityFile | null {
+ const identityPath = path.join(workspace, DEFAULT_IDENTITY_FILENAME);
+ return loadIdentityFromFile(identityPath);
+}
diff --git a/src/cli/program/register.agent.ts b/src/cli/program/register.agent.ts
index 048a91de0..d597efde9 100644
--- a/src/cli/program/register.agent.ts
+++ b/src/cli/program/register.agent.ts
@@ -139,7 +139,7 @@ ${theme.muted("Docs:")} ${formatDocsLink("/cli/agent", "docs.clawd.bot/cli/agent
agents
.command("set-identity")
- .description("Update an agent identity (name/theme/emoji)")
+ .description("Update an agent identity (name/theme/emoji/avatar)")
.option("--agent