OpenClaw agents

An OpenClaw agent is a workspace directory. Its Markdown files become the agent’s instructions, and a built-in coding toolchain — a shell, file editing, git, and search — is available without any declaration. AGENTS.md is the agent: what you write there is what the model is told about who it is and how to behave. Use this agent type when the work is best expressed as written instructions rather than code or a schema, and when the agent needs to read and edit files, run commands, or work in a repository as part of doing its job.

Create an OpenClaw agent

guild agent init --name my-openclaw-agent --agent-type openclaw

The scaffold includes:

my-agent/
├── AGENTS.md         # The agent's instructions — becomes the system prompt
├── guild.yaml        # Integrations, sub-agents, and built-in tools
├── README.md
└── .gitignore

Replace the template AGENTS.md with your agent’s instructions, then save and run the agent like you would any other Guild agent.

Open Agents in the left nav, click Your agents, then click Create Agent.
Under Or start another way, choose Start with code.
Choose OpenClaw Agent.
Replace the template AGENTS.md with your agent’s instructions.

Workspace files

Every file you commit is placed in the agent’s workspace. AGENTS.md is the only required one; the rest are optional, and a committed file always wins — Guild fills a gap but never overrides what you ship.

File	If you commit it	If you omit it
`AGENTS.md`	Becomes the agent’s instructions.	Build error.
`IDENTITY.md`	Used as written.	Generated from the agent’s Guild record.
`USER.md`	Used as written.	Generated from the session’s workspace context.
`SOUL.md`	Gives the agent a distinct persona and voice.	Omitted.
`MEMORY.md`	Seeds the agent’s memory on the first turn.	Restored from the task’s saved state on a continuation.

Two consequences of the committed-file-wins rule are worth knowing, because both are useful rather than accidental:

Committing a USER.md opts the agent out of workspace context injection.
Committing an IDENTITY.md that differs from the agent’s Guild record is not an error. The record drives the Agent Hub listing and the session UI; the file drives what the model believes about itself.

The workspace is rebuilt for each task from the version’s committed files, and versions are immutable, so the agent can write to its workspace freely without affecting later tasks.

Skills

A skill is a directory under skills/ containing a SKILL.md whose frontmatter carries a name and description:

my-agent/
├── AGENTS.md
├── guild.yaml
└── skills/
    └── research/
        └── SKILL.md

The agent loads a skill’s instructions only when the task calls for it, so skills add depth without spending context on every turn. Commit as many as you need; they are discovered from the workspace at run time.

A skills/<name>/ directory with no SKILL.md is a build error. Without that file the skill is silently never discovered, so the build rejects it rather than letting the agent run as though the skill was never written.

Tools

An OpenClaw agent has two separate sources of tools. The coding toolchain is built in. A shell, file editing, git, and search are always available and need no declaration. Guild-brokered tools are declared in guild.yaml at the root of the agent’s version files, as described in the guild.yaml reference. Each integration operation, sub-agent, and built-in tool you declare becomes a tool the agent can call. Omit guild.yaml when the agent needs none of them.

integrations:
  - name: acme~github
    version: ^1.4.0
    tools: [github_repos_get, github_issues_list]

sub_agents:
  - name: acme~research
    version: ^1.0.0

builtins:
  - name: ui
    tools: [ui_prompt]
  - name: guild

The built-in services available to an OpenClaw agent are:

Service	Tool	Behavior
`console`	`console_log`	Logs a message to the debug console. Does not suspend the task.
`ui`	`ui_prompt`	Prompts the user for additional information or clarification. Suspends the task.
`guild`	`guild_credentials_request`	Requests that the user configure credentials for a specific integration. Suspends the task.

See the guild.yaml reference for the field rules and validation.

The environment field is not supported for OpenClaw agents. An OpenClaw agent always runs in the standard guildai~lobsterpot image. Declaring it, or any other section an OpenClaw agent does not support, is a build error rather than being silently ignored.

Input and output

OpenClaw agents have a fixed text contract: they take text in and return text out. Unlike a Goose recipe, there are no declared parameters and no response JSON schema — the input and output schemas are applied for you at build time.

Build-time validation

Guild validates the agent when you save a version. The workspace is checked first, because an unrunnable workspace fails the build before any tool validation runs:

Validate agent workspace — AGENTS.md is present and non-empty, every committed path stays inside the workspace, and every skills/<name>/ directory has a SKILL.md.
Validate Guild integrations — each integration in guild.yaml resolves to a published version, and any listed tools map to real operations on it.
Validate Guild subagents — each sub-agent resolves to a published version.
Validate Guild builtins — each service is one of console, ui, or guild, and each listed tool is permitted for that service.
Store Guild tools — the resolved tool manifest is recorded on the version. Tool names must be unique across integrations, sub-agents, and builtins; a duplicate is a build error.

A public agent cannot depend on a private integration or a private sub-agent. See Versions for the full dependency visibility rules.

guild.yaml reference for every section an OpenClaw agent can declare
Agent skills for publishing skills your agent can load
Workspace context for instructions shared by every agent in a workspace
Agent types to compare all five agent types

Overview

The Smith

The Factory

Platform

Agent SDK

OpenClaw agents

Create an OpenClaw agent

Workspace files

Skills

Tools

Input and output

Build-time validation

​Create an OpenClaw agent

​Workspace files

​Skills

​Tools

​Input and output

​Build-time validation

​Related pages

Create an OpenClaw agent

Workspace files

Skills

Tools

Input and output

Build-time validation

Related pages