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.

From your Agents tab, 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, exactly as they are for Goose agents. 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.

The field rules and validation for integrations, sub_agents, and builtins are the same as for Goose agents — see Integrations and sub-agents.

The environment field is not supported for OpenClaw agents. An OpenClaw agent always runs in the standard guildai~lobsterpot image.

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.

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

Overview

The Smith

The Factory

Platform

Insights

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

Create an OpenClaw agent

Workspace files

Skills

Tools

Input and output

Build-time validation