Profiles

A profile is the bot definition TinyClaw runs for a session.

It answers one practical question: which bot should respond, and how should it behave?

Profiles belong to an organization. Switching orgs in the dashboard shows only that org's bots.

Default profile per organization

TinyClaw does not share one global default bot across every org.

When an organization is created — including the first org at install — TinyClaw automatically:

1. Creates one default profile for that org (isDefault: true)
2. Assigns the standard builtin tool set (web search, file tools, email, and the rest)
3. Initializes its soul directory on disk

That profile is named Default Bot and gets a unique id (not a fixed string like default).

What	Behavior
Default profile	Exactly one per org, marked with isDefault
Super bot	Not auto-created; platform admin may add a profile with isSuper: true if needed
Additional orgs	Each gets its own default profile and isolated on-disk data

If a session or channel config omits a profile id — or names one that does not exist in the active org — TinyClaw falls back to that org's default profile.

New custom profiles

Platform admins create extra profiles inside the active org. Each new profile gets its own soul directory and starts with only the builtin create_skill tool. Assign more tools, MCP servers, and skills from the dashboard.

What a profile contains

Field	What it means
id	Stable unique profile id
name	Human-friendly label shown in the UI
model	Optional model selection for this profile
systemPrompt	Base instructions stored in the database
isSuper	Marks the profile as a super profile with elevated behavior
isDefault	Marks the org's default profile used when none is specified
tools	Builtin or custom tools the profile is allowed to use
mcpServers	MCP servers available to the profile
skills	Reusable instructions assigned to the profile
hasAvatar	Whether the profile has a custom avatar
soulActive	Whether soul files are present and active

What a good profile usually represents

One profile should map to one clear purpose. Create another profile when you need different instructions, tools, tone, or knowledge.

How profiles affect replies

When a chat runs with a profile, TinyClaw builds the agent context in this order:

1. Start with the profile's systemPrompt
2. If soul files exist, compose them into the main system prompt
3. Append the assigned skills catalog
4. Append the knowledge base catalog
5. Expose only the tools allowed for that profile

So a profile is not just a name. It controls both:

• How the agent behaves
• What the agent is allowed to do

Soul vs system prompt

Profiles support two layers of instruction:

Layer	Best for
systemPrompt	Quick base instructions stored in the database
Soul files	Richer identity, style, operating rules, and memory on disk

Soul files, avatars, knowledge-base documents, and profile-scoped skills all live under an org-scoped path:

~/.tinyclaw/orgs/{orgId}/profiles/{profileId}/

Supported soul files:

File	Purpose
SOUL.md	Identity
STYLE.md	Writing voice
INSTRUCTIONS.md	Operating rules
MEMORY.md	Continuity across sessions
examples/*.md	Calibration examples

Profile-scoped skills are stored at:

~/.tinyclaw/orgs/{orgId}/profiles/{profileId}/skills/

If you want richer personality and clearer long-term behavior, use soul files. If you only need a quick setup, the stored systemPrompt may be enough.

Model selection

Each profile can optionally select its own model.

Field	Meaning
model	Uses a specific model for this profile instead of the workspace default

Knowledge base and memory

Profiles keep their own context on disk under the org-scoped profile directory:

• Knowledge base documents for searchable reference material
• MEMORY.md for facts and continuity saved by the agent

This data is isolated per org and per profile. Two orgs never read or write the same directory, even if profile ids happen to match.

Multi-tenant behavior

Profiles are tenant-owned data inside an organization:

Rule	Detail
Listing	GET /v1/profiles returns only profiles for the active org
Lookup	Requesting another org's profile id returns not found
Sessions	Bind to one profile within the active org
Tool access	Scoped per profile
Mutations	Platform-admin only; org members chat with org profiles

Org admins manage members, not profiles. Platform admins need an active org context when creating or editing profiles.

When to create multiple profiles

Create separate profiles when you need different:

• Agent identities
• Safety or operating rules
• Tool access
• Knowledge bases
• Models

Next steps

• Builtin tools — what each profile can do
• MCP servers — extend a profile with external tools
• Multi-tenancy — who can manage profiles and members