> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw agents

> Build agents from Markdown instructions and skills, with a coding toolchain built in.

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

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    guild agent init --name my-openclaw-agent --agent-type openclaw
    ```

    The scaffold includes:

    ```text theme={null}
    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.
  </Tab>

  <Tab title="Web">
    1. From your **Agents** tab, click **Create Agent**.
    2. Under **Or start another way**, choose **Start with code**.
    3. Choose **OpenClaw Agent**.
    4. Replace the template `AGENTS.md` with your agent's instructions.
  </Tab>
</Tabs>

## 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](/platform/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](/platform/skills) is a directory under `skills/` containing a `SKILL.md` whose frontmatter carries a name and description:

```text theme={null}
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.

<Note>
  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.
</Note>

## 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](/guide/goose-agents#integrations-and-sub-agents-guild-yaml). 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.

```yaml theme={null}
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](/guide/goose-agents#integrations-and-sub-agents-guild-yaml).

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

## 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:

1. **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`.
2. **Validate Guild integrations** — each integration in `guild.yaml` resolves to a published version, and any listed tools map to real operations on it.
3. **Validate Guild subagents** — each sub-agent resolves to a published version.
4. **Validate Guild builtins** — each service is one of `console`, `ui`, or `guild`, and each listed tool is permitted for that service.
5. **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](/guide/versions) for the full dependency visibility rules.