mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-06 05:51:15 +08:00
docs(skills): full rewrite of skills section with Mintlify components
Rewrites all skills documentation pages with rich Mintlify components (Steps, CardGroup, AccordionGroup, ParamField, Note, Warning, Tip) and code-verified accuracy throughout. - tools/skills.md: CardGroup quick-nav, verified precedence table from workspace.ts, Security accordions, Steps for env injection, token impact formula, Related CardGroup - tools/creating-skills.md: Steps walkthrough, gating accordion, propose-update command (was missing), Best practices Tip, ClawHub publish flow, Related CardGroup - tools/skills-config.md: ParamField for every config key, agent allowlist section, Workshop config, sandbox Warning - tools/slash-commands.md: CardGroup for 3 command types, command tables in AccordionGroup sections, ParamFields for all config keys, dedicated sections for /tools /model /config /mcp /debug /plugins /trace /btw - prose.md: Steps for install, CardGroup quick-nav, AccordionGroup for state backends, runtime mapping table docs.json: adds skill-workshop nav entry and redirects (/skill-workshop, /tools/skills-workshop -> /tools/skill-workshop)
This commit is contained in:
Vincent Koc
@@ -748,6 +748,14 @@
|
||||
"source": "/skills",
|
||||
"destination": "/tools/skills"
|
||||
},
|
||||
{
|
||||
"source": "/skill-workshop",
|
||||
"destination": "/tools/skill-workshop"
|
||||
},
|
||||
{
|
||||
"source": "/tools/skills-workshop",
|
||||
"destination": "/tools/skill-workshop"
|
||||
},
|
||||
{
|
||||
"source": "/skills-config",
|
||||
"destination": "/tools/skills-config"
|
||||
|
||||
174
docs/prose.md
174
docs/prose.md
@@ -1,43 +1,64 @@
|
||||
---
|
||||
summary: "OpenProse: .prose workflows, slash commands, and state in OpenClaw"
|
||||
read_when:
|
||||
- You want to run or write .prose workflows
|
||||
- You want to enable the OpenProse plugin
|
||||
- You need to understand state storage
|
||||
title: "OpenProse"
|
||||
sidebarTitle: "OpenProse"
|
||||
summary: "OpenProse is a markdown-first workflow format for multi-agent AI sessions. In OpenClaw it ships as a plugin with a /prose slash command and a skill pack."
|
||||
read_when:
|
||||
- You want to run or write .prose workflow files
|
||||
- You want to enable the OpenProse plugin
|
||||
- You need to understand how OpenProse maps to OpenClaw primitives
|
||||
---
|
||||
|
||||
OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In OpenClaw it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
|
||||
OpenProse is a portable, markdown-first workflow format for orchestrating AI
|
||||
sessions. In OpenClaw it ships as a plugin that installs an OpenProse skill
|
||||
pack and a `/prose` slash command. Programs live in `.prose` files and can
|
||||
spawn multiple sub-agents with explicit control flow.
|
||||
|
||||
Official site: [https://www.prose.md](https://www.prose.md)
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Install" icon="download" href="#install">
|
||||
Enable the OpenProse plugin and restart the Gateway.
|
||||
</Card>
|
||||
<Card title="Run a program" icon="play" href="#slash-command">
|
||||
Use `/prose run` to execute a `.prose` file or remote program.
|
||||
</Card>
|
||||
<Card title="Write programs" icon="pencil" href="#example">
|
||||
Author multi-agent workflows with parallel and sequential steps.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## What it can do
|
||||
## Install
|
||||
|
||||
- Multi-agent research + synthesis with explicit parallelism.
|
||||
- Repeatable approval-safe workflows (code review, incident triage, content pipelines).
|
||||
- Reusable `.prose` programs you can run across supported agent runtimes.
|
||||
<Steps>
|
||||
<Step title="Enable the plugin">
|
||||
Bundled plugins are disabled by default. Enable OpenProse:
|
||||
|
||||
## Install + enable
|
||||
```bash
|
||||
openclaw plugins enable open-prose
|
||||
```
|
||||
|
||||
Bundled plugins are disabled by default. Enable OpenProse:
|
||||
</Step>
|
||||
<Step title="Restart the Gateway">
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify">
|
||||
```bash
|
||||
openclaw plugins list | grep prose
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw plugins enable open-prose
|
||||
```
|
||||
You should see `open-prose` as enabled. The `/prose` skill command is now
|
||||
available in chat.
|
||||
|
||||
Restart the Gateway after enabling the plugin.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Dev/local checkout: `openclaw plugins install ./path/to/local/open-prose-plugin`
|
||||
|
||||
Related docs: [Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
|
||||
For a local checkout: `openclaw plugins install ./path/to/local/open-prose-plugin`
|
||||
|
||||
## Slash command
|
||||
|
||||
OpenProse registers `/prose` as a user-invocable skill command. It routes to the OpenProse VM instructions and uses OpenClaw tools under the hood.
|
||||
OpenProse registers `/prose` as a user-invocable skill command:
|
||||
|
||||
Common commands:
|
||||
|
||||
```
|
||||
```text
|
||||
/prose help
|
||||
/prose run <file.prose>
|
||||
/prose run <handle/slug>
|
||||
@@ -47,7 +68,16 @@ Common commands:
|
||||
/prose update
|
||||
```
|
||||
|
||||
## Example: a simple `.prose` file
|
||||
`/prose run <handle/slug>` resolves to `https://p.prose.md/<handle>/<slug>`.
|
||||
Direct URLs are fetched as-is using the `web_fetch` tool.
|
||||
|
||||
## What it can do
|
||||
|
||||
- Multi-agent research and synthesis with explicit parallelism.
|
||||
- Repeatable, approval-safe workflows (code review, incident triage, content pipelines).
|
||||
- Reusable `.prose` programs you can run across supported agent runtimes.
|
||||
|
||||
## Example: parallel research and synthesis
|
||||
|
||||
```prose
|
||||
# Research + synthesis with two agents running in parallel.
|
||||
@@ -72,11 +102,27 @@ session "Merge the findings + draft into a final answer."
|
||||
context: { findings, draft }
|
||||
```
|
||||
|
||||
## OpenClaw runtime mapping
|
||||
|
||||
OpenProse programs map to OpenClaw primitives:
|
||||
|
||||
| OpenProse concept | OpenClaw tool |
|
||||
| ------------------------- | ---------------- |
|
||||
| Spawn session / Task tool | `sessions_spawn` |
|
||||
| File read / write | `read` / `write` |
|
||||
| Web fetch | `web_fetch` |
|
||||
|
||||
<Warning>
|
||||
If your tool allowlist blocks `sessions_spawn`, `read`, `write`, or
|
||||
`web_fetch`, OpenProse programs will fail. Check your
|
||||
[tools allowlist config](/gateway/config-tools).
|
||||
</Warning>
|
||||
|
||||
## File locations
|
||||
|
||||
OpenProse keeps state under `.prose/` in your workspace:
|
||||
|
||||
```
|
||||
```text
|
||||
.prose/
|
||||
├── .env
|
||||
├── runs/
|
||||
@@ -90,48 +136,56 @@ OpenProse keeps state under `.prose/` in your workspace:
|
||||
|
||||
User-level persistent agents live at:
|
||||
|
||||
```
|
||||
```text
|
||||
~/.prose/agents/
|
||||
```
|
||||
|
||||
## State modes
|
||||
## State backends
|
||||
|
||||
OpenProse supports multiple state backends:
|
||||
<AccordionGroup>
|
||||
<Accordion title="filesystem (default)">
|
||||
State is written to `.prose/runs/...` in the workspace. No extra
|
||||
dependencies required.
|
||||
</Accordion>
|
||||
<Accordion title="in-context">
|
||||
Transient state kept in the context window. Suitable for small, short-lived
|
||||
programs.
|
||||
</Accordion>
|
||||
<Accordion title="sqlite (experimental)">
|
||||
Requires the `sqlite3` binary on `PATH`.
|
||||
</Accordion>
|
||||
<Accordion title="postgres (experimental)">
|
||||
Requires `psql` and a connection string.
|
||||
|
||||
- **filesystem** (default): `.prose/runs/...`
|
||||
- **in-context**: transient, for small programs
|
||||
- **sqlite** (experimental): requires `sqlite3` binary
|
||||
- **postgres** (experimental): requires `psql` and a connection string
|
||||
<Warning>
|
||||
Postgres credentials flow into sub-agent logs. Use a dedicated,
|
||||
least-privileged database.
|
||||
</Warning>
|
||||
|
||||
Notes:
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
- sqlite/postgres are opt-in and experimental.
|
||||
- postgres credentials flow into subagent logs; use a dedicated, least-privileged DB.
|
||||
## Security
|
||||
|
||||
## Remote programs
|
||||
|
||||
`/prose run <handle/slug>` resolves to `https://p.prose.md/<handle>/<slug>`.
|
||||
Direct URLs are fetched as-is. This uses the `web_fetch` tool (or `exec` for POST).
|
||||
|
||||
## OpenClaw runtime mapping
|
||||
|
||||
OpenProse programs map to OpenClaw primitives:
|
||||
|
||||
| OpenProse concept | OpenClaw tool |
|
||||
| ------------------------- | ---------------- |
|
||||
| Spawn session / Task tool | `sessions_spawn` |
|
||||
| File read/write | `read` / `write` |
|
||||
| Web fetch | `web_fetch` |
|
||||
|
||||
If your tool allowlist blocks these tools, OpenProse programs will fail. See [Skills config](/tools/skills-config).
|
||||
|
||||
## Security + approvals
|
||||
|
||||
Treat `.prose` files like code. Review before running. Use OpenClaw tool allowlists and approval gates to control side effects.
|
||||
|
||||
For deterministic, approval-gated workflows, compare with [Lobster](/tools/lobster).
|
||||
Treat `.prose` files like code. Review them before running. Use OpenClaw tool
|
||||
allowlists and approval gates to control side effects. For deterministic,
|
||||
approval-gated workflows, compare with [Lobster](/tools/lobster).
|
||||
|
||||
## Related
|
||||
|
||||
- [Text-to-speech](/tools/tts)
|
||||
- [Markdown formatting](/concepts/markdown-formatting)
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Skills reference" href="/tools/skills" icon="puzzle-piece">
|
||||
How OpenProse's skill pack loads and what gates apply.
|
||||
</Card>
|
||||
<Card title="Subagents" href="/tools/subagents" icon="users">
|
||||
OpenClaw's native multi-agent coordination layer.
|
||||
</Card>
|
||||
<Card title="Text-to-speech" href="/tools/tts" icon="volume-high">
|
||||
Add audio output to your workflows.
|
||||
</Card>
|
||||
<Card title="Slash commands" href="/tools/slash-commands" icon="terminal">
|
||||
All available chat commands including /prose.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Official site: [https://www.prose.md](https://www.prose.md)
|
||||
|
||||
@@ -1,81 +1,76 @@
|
||||
---
|
||||
summary: "Build and test custom workspace skills with SKILL.md"
|
||||
title: "Creating skills"
|
||||
sidebarTitle: "Creating skills"
|
||||
summary: "Build, test, and publish custom SKILL.md workspace skills for your OpenClaw agents."
|
||||
read_when:
|
||||
- You are creating a new custom skill in your workspace
|
||||
- You are creating a new custom skill
|
||||
- You need a quick starter workflow for SKILL.md-based skills
|
||||
- You want to use Skill Workshop to propose a skill for agent review
|
||||
---
|
||||
|
||||
Skills teach the agent how and when to use tools. Each skill is a directory
|
||||
containing a `SKILL.md` file with YAML frontmatter and markdown instructions.
|
||||
|
||||
For how skills are loaded and prioritized, see [Skills](/tools/skills). For
|
||||
agent-generated or reviewed skill changes, see
|
||||
[Skill Workshop](/tools/skill-workshop).
|
||||
OpenClaw loads skills from several roots in a defined [precedence order](/tools/skills#loading-order).
|
||||
|
||||
## Create your first skill
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the skill directory">
|
||||
Skills live in your workspace. Create a new folder:
|
||||
Skills live in your workspace `skills/` folder. Create a directory for your
|
||||
new skill:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.openclaw/workspace/skills/hello-world
|
||||
```
|
||||
|
||||
You can group skills in subfolders when your library grows:
|
||||
You can group skills in subfolders for organization — the skill is still
|
||||
named by the `SKILL.md` frontmatter, not the folder path:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
|
||||
# skill name is still "hello-world", invoked as /hello-world
|
||||
```
|
||||
|
||||
Group folders are only organizational. The skill is still named by
|
||||
`SKILL.md` frontmatter, so `name: hello-world` is invoked as
|
||||
`/hello-world`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Write SKILL.md">
|
||||
Create `SKILL.md` inside that directory. The frontmatter defines metadata,
|
||||
and the markdown body contains instructions for the agent.
|
||||
Create `SKILL.md` inside the directory. The frontmatter defines metadata;
|
||||
the body gives the agent instructions.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: hello-world
|
||||
description: A simple skill that says hello.
|
||||
description: A simple skill that prints a greeting.
|
||||
---
|
||||
|
||||
# Hello World Skill
|
||||
# Hello World
|
||||
|
||||
When the user asks for a greeting, use the `echo` tool to say
|
||||
"Hello from your custom skill!".
|
||||
When the user asks for a greeting, use the `exec` tool to run:
|
||||
|
||||
```bash
|
||||
echo "Hello from your custom skill!"
|
||||
```
|
||||
```
|
||||
|
||||
Use hyphen-case with lowercase letters, digits, and hyphens for the skill
|
||||
`name`. Keep the leaf folder name and frontmatter `name` aligned.
|
||||
Naming rules:
|
||||
- Use lowercase letters, digits, and hyphens for `name`.
|
||||
- Keep the directory name and frontmatter `name` aligned.
|
||||
- `description` is shown to the agent and in slash-command discovery —
|
||||
keep it one line and under 160 characters.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Add tools (optional)">
|
||||
You can define custom tool schemas in the frontmatter or instruct the agent
|
||||
to use existing system tools (like `exec` or `browser`). Skills can also
|
||||
ship inside plugins alongside the tools they document.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Load the skill">
|
||||
Verify the skill loaded:
|
||||
|
||||
<Step title="Verify the skill loaded">
|
||||
```bash
|
||||
openclaw skills list
|
||||
```
|
||||
|
||||
OpenClaw watches nested `SKILL.md` files under skills roots. If the watcher
|
||||
is disabled or you are continuing an existing session, start a new session
|
||||
so the model receives the refreshed skills list:
|
||||
OpenClaw watches `SKILL.md` files under skills roots by default. If the
|
||||
watcher is disabled or you are continuing an existing session, start a new
|
||||
one so the agent receives the refreshed list:
|
||||
|
||||
```bash
|
||||
# From chat
|
||||
# From chat — archive current session and start fresh
|
||||
/new
|
||||
|
||||
# Or restart the gateway
|
||||
@@ -91,111 +86,186 @@ agent-generated or reviewed skill changes, see
|
||||
openclaw agent --message "give me a greeting"
|
||||
```
|
||||
|
||||
Or just chat with the agent and ask for a greeting.
|
||||
Or open a chat and ask the agent directly. Use `/skill hello-world` to
|
||||
invoke it explicitly by name.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Use Skill Workshop for generated skills
|
||||
## SKILL.md reference
|
||||
|
||||
For agent-generated procedures, use Skill Workshop instead of writing `SKILL.md`
|
||||
directly. Skill Workshop creates a pending proposal first; it becomes an active
|
||||
skill only after review and apply:
|
||||
### Required fields
|
||||
|
||||
| Field | Description |
|
||||
| ------------- | --------------------------------------------------------------- |
|
||||
| `name` | Unique slug using lowercase letters, digits, and hyphens |
|
||||
| `description` | One-line description shown to the agent and in discovery output |
|
||||
|
||||
### Optional frontmatter keys
|
||||
|
||||
| Field | Default | Description |
|
||||
| -------------------------- | ------- | -------------------------------------------------------------------------------- |
|
||||
| `user-invocable` | `true` | Expose the skill as a user slash command |
|
||||
| `disable-model-invocation` | `false` | Keep the skill out of the agent's system prompt (still runs via `/skill`) |
|
||||
| `command-dispatch` | — | Set to `tool` to route the slash command directly to a tool, bypassing the model |
|
||||
| `command-tool` | — | Tool name to invoke when `command-dispatch: tool` is set |
|
||||
| `command-arg-mode` | `raw` | For tool dispatch, forwards the raw args string to the tool |
|
||||
| `homepage` | — | URL shown as "Website" in the macOS Skills UI |
|
||||
|
||||
For gating fields (`requires.bins`, `requires.env`, etc.) see
|
||||
[Skills — Gating](/tools/skills#gating).
|
||||
|
||||
### Using `{baseDir}`
|
||||
|
||||
Use `{baseDir}` in the skill body to reference files inside the skill
|
||||
directory without hardcoding paths:
|
||||
|
||||
```markdown
|
||||
Run the helper script at `{baseDir}/scripts/run.sh`.
|
||||
```
|
||||
|
||||
## Adding conditional activation
|
||||
|
||||
Gate your skill so it only loads when its dependencies are available:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: gemini-search
|
||||
description: Search using Gemini CLI.
|
||||
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
|
||||
---
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Gating options">
|
||||
| Key | Description |
|
||||
| --- | --- |
|
||||
| `requires.bins` | All binaries must exist on `PATH` |
|
||||
| `requires.anyBins` | At least one binary must exist on `PATH` |
|
||||
| `requires.env` | Each env var must exist in the process or config |
|
||||
| `requires.config` | Each `openclaw.json` path must be truthy |
|
||||
| `os` | Platform filter: `["darwin"]`, `["linux"]`, `["win32"]` |
|
||||
| `always` | Set `true` to skip all gates and always include the skill |
|
||||
|
||||
Full reference: [Skills — Gating](/tools/skills#gating).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Environment and API keys">
|
||||
Wire an API key to a skill entry in `openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
skills: {
|
||||
entries: {
|
||||
"gemini-search": {
|
||||
enabled: true,
|
||||
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The key is injected into the host process for that agent turn only.
|
||||
It does not reach the sandbox — see
|
||||
[sandboxed env vars](/tools/skills-config#sandboxed-skills-and-env-vars).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Propose via Skill Workshop
|
||||
|
||||
For agent-drafted skills or when you want operator review before a skill goes
|
||||
live, use [Skill Workshop](/tools/skill-workshop) proposals instead of writing
|
||||
`SKILL.md` directly.
|
||||
|
||||
```bash
|
||||
# Propose a brand-new skill
|
||||
openclaw skills workshop propose-create \
|
||||
--name "hello-world" \
|
||||
--description "A simple skill that says hello." \
|
||||
--description "A simple skill that prints a greeting." \
|
||||
--proposal ./PROPOSAL.md
|
||||
|
||||
# Propose an update to an existing skill
|
||||
openclaw skills workshop propose-update hello-world \
|
||||
--proposal ./PROPOSAL.md \
|
||||
--description "Updated greeting skill"
|
||||
```
|
||||
|
||||
Use `--proposal-dir` when the proposal also has support files:
|
||||
Use `--proposal-dir` when the proposal includes support files:
|
||||
|
||||
```bash
|
||||
openclaw skills workshop propose-create \
|
||||
--name "hello-world" \
|
||||
--description "A simple skill that says hello." \
|
||||
--proposal-dir ./hello-world-proposal
|
||||
--description "A simple skill that prints a greeting." \
|
||||
--proposal-dir ./hello-world-proposal/
|
||||
```
|
||||
|
||||
The proposal stays inactive until an operator reviews and applies it.
|
||||
Proposal directories must contain `PROPOSAL.md`. Support files can be included
|
||||
under `assets/`, `examples/`, `references/`, `scripts/`, or `templates/`:
|
||||
The directory must contain `PROPOSAL.md`. Support files can go in `assets/`,
|
||||
`examples/`, `references/`, `scripts/`, or `templates/`.
|
||||
|
||||
After review:
|
||||
|
||||
```bash
|
||||
openclaw skills workshop inspect <proposal-id>
|
||||
openclaw skills workshop revise <proposal-id> --proposal ./PROPOSAL.md
|
||||
openclaw skills workshop apply <proposal-id>
|
||||
```
|
||||
|
||||
When applied, OpenClaw writes the final `SKILL.md` into the workspace `skills/`
|
||||
root, writes approved support files beside it, and removes proposal-only
|
||||
frontmatter such as `status: proposal`, proposal `version`, and proposal
|
||||
`date`.
|
||||
See [Skill Workshop](/tools/skill-workshop) for the full proposal lifecycle.
|
||||
|
||||
Full proposal storage, review, Gateway, and approval-policy details are in
|
||||
[Skill Workshop](/tools/skill-workshop).
|
||||
## Publishing to ClawHub
|
||||
|
||||
## Skill metadata reference
|
||||
<Steps>
|
||||
<Step title="Ensure your SKILL.md is complete">
|
||||
Make sure `name`, `description`, and any `metadata.openclaw` gating fields
|
||||
are set. Add a `homepage` URL if you have a project page.
|
||||
</Step>
|
||||
<Step title="Install the ClawHub skill">
|
||||
The ClawHub skill documents the current publish command shape and required
|
||||
metadata:
|
||||
|
||||
The YAML frontmatter supports these fields:
|
||||
```bash
|
||||
openclaw skills install clawhub-publish
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
| ----------------------------------- | -------- | -------------------------------------------------------------- |
|
||||
| `name` | Yes | Unique identifier using lowercase letters, digits, and hyphens |
|
||||
| `description` | Yes | One-line description shown to the agent |
|
||||
| `metadata.openclaw.os` | No | OS filter (`["darwin"]`, `["linux"]`, etc.) |
|
||||
| `metadata.openclaw.requires.bins` | No | Required binaries on PATH |
|
||||
| `metadata.openclaw.requires.config` | No | Required config keys |
|
||||
</Step>
|
||||
<Step title="Publish">
|
||||
```bash
|
||||
clawhub publish
|
||||
```
|
||||
|
||||
## Advanced features
|
||||
See [ClawHub — Publishing](/clawhub/publishing) for the full flow.
|
||||
|
||||
Once a basic skill works, these fields help make it reliable and portable:
|
||||
|
||||
- **Conditional activation** — use `requires.bins`, `requires.env`, or
|
||||
`requires.config` to load the skill only when required dependencies are
|
||||
available. See [Skills reference: gating](/tools/skills#gating).
|
||||
- **Environment and API-key wiring** — use `skills.entries.<name>.env` and
|
||||
`skills.entries.<name>.apiKey` to inject host-side environment for a skill
|
||||
turn. See [Skills reference: config wiring](/tools/skills#config-wiring).
|
||||
- **Invocation control** — set `user-invocable: false` to hide a slash command,
|
||||
or `disable-model-invocation: true` to keep a command-style skill out of the
|
||||
model prompt. See [Skills reference: frontmatter](/tools/skills#frontmatter).
|
||||
- **Direct command dispatch** — use `command-dispatch: tool` with
|
||||
`command-tool` when a slash command should call a tool directly instead of
|
||||
routing through the model.
|
||||
- **Portable paths** — use `{baseDir}` in `SKILL.md` when referencing scripts
|
||||
or assets inside the skill directory.
|
||||
- **Publishing** — use the ClawHub skill when preparing a skill for publication.
|
||||
It documents the current `clawhub publish` command shape and required
|
||||
metadata.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Best practices
|
||||
|
||||
- **Be concise** — instruct the model on _what_ to do, not how to be an AI
|
||||
- **Safety first** — if your skill uses `exec`, ensure prompts don't allow arbitrary command injection from untrusted input
|
||||
- **Test locally** — use `openclaw agent --message "..."` to test before sharing
|
||||
- **Use ClawHub** — browse and contribute skills at [ClawHub](https://clawhub.ai)
|
||||
|
||||
## Where skills live
|
||||
|
||||
| Location | Precedence | Scope |
|
||||
| ------------------------------- | ---------- | --------------------- |
|
||||
| `\<workspace\>/skills/` | Highest | Per-agent |
|
||||
| `\<workspace\>/.agents/skills/` | High | Per-workspace agent |
|
||||
| `~/.agents/skills/` | Medium | Shared agent profile |
|
||||
| `~/.openclaw/skills/` | Medium | Shared (all agents) |
|
||||
| Bundled (shipped with OpenClaw) | Low | Global |
|
||||
| `skills.load.extraDirs` | Lowest | Custom shared folders |
|
||||
|
||||
Each skills root can contain direct skill folders such as
|
||||
`skills/hello-world/SKILL.md` or grouped folders such as
|
||||
`skills/personal/hello-world/SKILL.md`.
|
||||
<Tip>
|
||||
- **Be concise** — instruct the model on *what* to do, not how to be an AI.
|
||||
- **Safety first** — if your skill uses `exec`, ensure prompts do not allow
|
||||
arbitrary command injection from untrusted input.
|
||||
- **Test locally** — use `openclaw agent --message "..."` before sharing.
|
||||
- **Use ClawHub** — browse community skills at [clawhub.ai](https://clawhub.ai)
|
||||
before building from scratch.
|
||||
</Tip>
|
||||
|
||||
## Related
|
||||
|
||||
- [Skills reference](/tools/skills) — loading, precedence, and gating rules
|
||||
- [Skill Workshop](/tools/skill-workshop) — governed creation for generated or reviewed skill changes
|
||||
- [Skills config](/tools/skills-config) — `skills.*` config schema
|
||||
- [ClawHub](/clawhub) — public skill registry
|
||||
- [Building Plugins](/plugins/building-plugins) — plugins can ship skills
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Skills reference" href="/tools/skills" icon="puzzle-piece">
|
||||
Loading order, gating, allowlists, and SKILL.md format.
|
||||
</Card>
|
||||
<Card title="Skill Workshop" href="/tools/skill-workshop" icon="flask">
|
||||
Proposal queue for agent-drafted skills.
|
||||
</Card>
|
||||
<Card title="Skills config" href="/tools/skills-config" icon="gear">
|
||||
Full `skills.*` config schema.
|
||||
</Card>
|
||||
<Card title="ClawHub" href="/clawhub" icon="cloud">
|
||||
Browse and publish skills on the public registry.
|
||||
</Card>
|
||||
<Card title="Building plugins" href="/plugins/building-plugins" icon="plug">
|
||||
Plugins can ship skills alongside the tools they document.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -1,47 +1,43 @@
|
||||
---
|
||||
summary: "Skills config schema and examples"
|
||||
read_when:
|
||||
- Adding or modifying skills config
|
||||
- Adjusting bundled allowlist or install behavior
|
||||
title: "Skills config"
|
||||
sidebarTitle: "Skills config"
|
||||
summary: "Full reference for the skills.* config schema, agent allowlists, workshop settings, and sandbox env var handling."
|
||||
read_when:
|
||||
- Configuring skill loading, install, or gating behavior
|
||||
- Setting per-agent skill visibility
|
||||
- Adjusting Skill Workshop limits or approval policy
|
||||
---
|
||||
|
||||
Most skills loader/install configuration lives under `skills` in
|
||||
`~/.openclaw/openclaw.json`. Agent-specific skill visibility lives under
|
||||
`agents.defaults.skills` and `agents.list[].skills`. Skill Workshop behavior is
|
||||
configured under `skills.workshop`; see
|
||||
[Skill Workshop](/tools/skill-workshop) for the full creation and review flow.
|
||||
Most skills configuration lives under `skills` in
|
||||
`~/.openclaw/openclaw.json`. Agent-specific visibility lives under
|
||||
`agents.defaults.skills` and `agents.list[].skills`.
|
||||
|
||||
```json5
|
||||
{
|
||||
skills: {
|
||||
allowBundled: ["gemini", "peekaboo"],
|
||||
load: {
|
||||
extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
|
||||
extraDirs: ["~/Projects/agent-scripts/skills"],
|
||||
allowSymlinkTargets: ["~/Projects/manager/skills"],
|
||||
watch: true,
|
||||
watchDebounceMs: 250,
|
||||
},
|
||||
install: {
|
||||
preferBrew: true,
|
||||
nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
|
||||
nodeManager: "npm",
|
||||
allowUploadedArchives: false,
|
||||
},
|
||||
workshop: {
|
||||
autonomous: {
|
||||
enabled: false,
|
||||
},
|
||||
approvalPolicy: "pending", // pending | auto
|
||||
autonomous: { enabled: false },
|
||||
approvalPolicy: "pending",
|
||||
maxPending: 50,
|
||||
maxSkillBytes: 40000,
|
||||
},
|
||||
entries: {
|
||||
"image-lab": {
|
||||
enabled: true,
|
||||
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
|
||||
env: {
|
||||
GEMINI_API_KEY: "GEMINI_KEY_HERE",
|
||||
},
|
||||
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
|
||||
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
|
||||
},
|
||||
peekaboo: { enabled: true },
|
||||
sag: { enabled: false },
|
||||
@@ -50,102 +46,148 @@ configured under `skills.workshop`; see
|
||||
}
|
||||
```
|
||||
|
||||
For built-in image generation/editing, prefer `agents.defaults.imageGenerationModel`
|
||||
plus the core `image_generate` tool. `skills.entries.*` is only for custom or
|
||||
third-party skill workflows.
|
||||
<Note>
|
||||
For built-in image generation, use `agents.defaults.imageGenerationModel`
|
||||
plus the core `image_generate` tool instead of `skills.entries`. Skill
|
||||
entries are for custom or third-party skill workflows only.
|
||||
</Note>
|
||||
|
||||
If you select a specific image provider/model, also configure that provider's
|
||||
auth/API key. Typical examples: `GEMINI_API_KEY` or `GOOGLE_API_KEY` for
|
||||
`google/*`, `OPENAI_API_KEY` for `openai/*`, and `FAL_KEY` for `fal/*`.
|
||||
## Loading (`skills.load`)
|
||||
|
||||
Examples:
|
||||
<ParamField path="skills.load.extraDirs" type="string[]">
|
||||
Additional skill directories to scan, at the lowest precedence (after bundled
|
||||
and plugin skills). Paths are expanded with `~` support.
|
||||
</ParamField>
|
||||
|
||||
- Native Nano Banana Pro-style setup: `agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"`
|
||||
- Native fal setup: `agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"`
|
||||
<ParamField path="skills.load.allowSymlinkTargets" type="string[]">
|
||||
Trusted real target directories that symlinked skill folders may resolve into,
|
||||
even when the symlink lives outside the configured root. Use this for
|
||||
intentional sibling-repo layouts such as
|
||||
`<workspace>/skills/manager -> ~/Projects/manager/skills`. Keep this list
|
||||
narrow — do not point at broad roots like `~` or `~/Projects`.
|
||||
</ParamField>
|
||||
|
||||
## Agent skill allowlists
|
||||
<ParamField path="skills.load.watch" type="boolean" default="true">
|
||||
Watch skill folders and refresh the skills snapshot when `SKILL.md` files
|
||||
change. Covers nested files under grouped skill roots.
|
||||
</ParamField>
|
||||
|
||||
Use agent config when you want the same machine/workspace skill roots, but a
|
||||
<ParamField path="skills.load.watchDebounceMs" type="number" default="250">
|
||||
Debounce window for skill watcher events in milliseconds.
|
||||
</ParamField>
|
||||
|
||||
## Install (`skills.install`)
|
||||
|
||||
<ParamField path="skills.install.preferBrew" type="boolean" default="true">
|
||||
Prefer Homebrew installers when `brew` is available.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.install.nodeManager" type='"npm" | "pnpm" | "yarn" | "bun"' default='"npm"'>
|
||||
Node package manager preference for skill installs. This only affects skill
|
||||
installs — the Gateway runtime should still use Node (Bun is not recommended
|
||||
for WhatsApp/Telegram). Use `openclaw setup --node-manager` for npm, pnpm,
|
||||
or bun; set `"yarn"` manually for Yarn-backed skill installs.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.install.allowUploadedArchives" type="boolean" default="false">
|
||||
Allow trusted `operator.admin` Gateway clients to install private zip
|
||||
archives staged through `skills.upload.*`. Normal ClawHub installs do not
|
||||
need this setting.
|
||||
</ParamField>
|
||||
|
||||
## Bundled skill allowlist
|
||||
|
||||
<ParamField path="skills.allowBundled" type="string[]">
|
||||
Optional allowlist for **bundled** skills only. When set, only bundled skills
|
||||
in the list are eligible. Managed, agent-level, and workspace skills are
|
||||
unaffected.
|
||||
</ParamField>
|
||||
|
||||
## Per-skill entries (`skills.entries`)
|
||||
|
||||
Keys under `entries` match the skill `name` by default. If a skill defines
|
||||
`metadata.openclaw.skillKey`, use that key instead. Quote hyphenated names
|
||||
(JSON5 allows quoted keys).
|
||||
|
||||
<ParamField path="skills.entries.<key>.enabled" type="boolean">
|
||||
`false` disables the skill even when bundled or installed. The `coding-agent`
|
||||
bundled skill is opt-in — set it to `true` and ensure one of `claude`,
|
||||
`codex`, `opencode`, or another supported CLI is installed and authenticated.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.entries.<key>.apiKey" type='string | { source, provider, id }'>
|
||||
Convenience field for skills that declare `metadata.openclaw.primaryEnv`.
|
||||
Supports a plaintext string or a SecretRef: `{ source: "env", provider: "default", id: "VAR_NAME" }`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.entries.<key>.env" type="Record<string, string>">
|
||||
Environment variables injected for the agent run. Only injected when the
|
||||
variable is not already set in the process.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.entries.<key>.config" type="object">
|
||||
Optional bag for custom per-skill configuration fields.
|
||||
</ParamField>
|
||||
|
||||
## Agent allowlists (`agents`)
|
||||
|
||||
Use agent config when you want the same machine/workspace skill roots but a
|
||||
different visible skill set per agent.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
skills: ["github", "weather"],
|
||||
skills: ["github", "weather"], // shared baseline
|
||||
},
|
||||
list: [
|
||||
{ id: "writer" }, // inherits defaults -> github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
|
||||
{ id: "writer" }, // inherits github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults entirely
|
||||
{ id: "locked-down", skills: [] }, // no skills
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
<ParamField path="agents.defaults.skills" type="string[]">
|
||||
Shared baseline allowlist inherited by agents that omit `agents.list[].skills`.
|
||||
Omit entirely to leave skills unrestricted by default.
|
||||
</ParamField>
|
||||
|
||||
- `agents.defaults.skills`: shared baseline allowlist for agents that omit
|
||||
`agents.list[].skills`.
|
||||
- Omit `agents.defaults.skills` to leave skills unrestricted by default.
|
||||
- `agents.list[].skills`: explicit final skill set for that agent; it does not
|
||||
merge with defaults.
|
||||
- `agents.list[].skills: []`: expose no skills for that agent.
|
||||
<ParamField path="agents.list[].skills" type="string[]">
|
||||
Explicit final skill set for that agent. Explicit lists **replace** inherited
|
||||
defaults — they do not merge. Set to `[]` to expose no skills for that agent.
|
||||
</ParamField>
|
||||
|
||||
## Fields
|
||||
## Workshop (`skills.workshop`)
|
||||
|
||||
- Built-in skill roots always include `~/.openclaw/skills`, `~/.agents/skills`,
|
||||
`<workspace>/.agents/skills`, and `<workspace>/skills`.
|
||||
- `allowBundled`: optional allowlist for **bundled** skills only. When set, only
|
||||
bundled skills in the list are eligible (managed, agent, and workspace skills unaffected).
|
||||
- `load.extraDirs`: additional skill directories to scan (lowest precedence).
|
||||
- `load.allowSymlinkTargets`: trusted real target directories that symlinked
|
||||
workspace, project-agent, or extra-dir skill folders may resolve into even
|
||||
when the symlink lives outside that target root. Use this for intentional
|
||||
sibling-repo layouts such as
|
||||
`<workspace>/skills/manager -> ~/Projects/manager/skills`. Managed
|
||||
`~/.openclaw/skills` and personal `~/.agents/skills` roots may follow
|
||||
skill-directory symlinks from local skill managers by default, but every
|
||||
`SKILL.md` still has to resolve inside its own skill directory.
|
||||
- `load.watch`: watch skill folders and refresh the skills snapshot (default: true).
|
||||
- `load.watchDebounceMs`: debounce for skill watcher events in milliseconds (default: 250).
|
||||
- `install.preferBrew`: prefer brew installers when available (default: true).
|
||||
- `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm).
|
||||
This only affects **skill installs**; the Gateway runtime should still be Node
|
||||
(Bun not recommended for WhatsApp/Telegram).
|
||||
- `openclaw setup --node-manager` is narrower and currently accepts `npm`,
|
||||
`pnpm`, or `bun`. Set `skills.install.nodeManager: "yarn"` manually if you
|
||||
want Yarn-backed skill installs.
|
||||
- `install.allowUploadedArchives`: allow trusted `operator.admin` Gateway
|
||||
clients to install private zip archives staged through `skills.upload.*`
|
||||
(default: false). This only enables the uploaded-archive path; normal ClawHub
|
||||
installs do not require it.
|
||||
- `workshop.autonomous.enabled`: allow agents to create pending proposals from
|
||||
durable conversation signals after successful turns (default: false).
|
||||
User-prompted skill creation still goes through Skill Workshop.
|
||||
- `workshop.approvalPolicy`: Skill Workshop review policy. `pending` requires
|
||||
approval before agent-initiated apply/reject/quarantine actions; `auto`
|
||||
allows those actions without approval.
|
||||
- `workshop.maxPending`: maximum pending/quarantined proposals retained per
|
||||
workspace (default: 50).
|
||||
- `workshop.maxSkillBytes`: maximum generated proposal body size in bytes
|
||||
(default: 40000).
|
||||
Proposal descriptions are also hard-capped at 160 bytes because they can be
|
||||
shown in skill discovery and proposal listings.
|
||||
- `entries.<skillKey>`: per-skill overrides.
|
||||
- `agents.defaults.skills`: optional default skill allowlist inherited by agents
|
||||
that omit `agents.list[].skills`.
|
||||
- `agents.list[].skills`: optional per-agent final skill allowlist; explicit
|
||||
lists replace inherited defaults instead of merging.
|
||||
<ParamField path="skills.workshop.autonomous.enabled" type="boolean" default="false">
|
||||
When `true`, agents can create pending proposals from durable conversation
|
||||
signals after successful turns. User-prompted skill creation always goes
|
||||
through Skill Workshop regardless of this setting.
|
||||
</ParamField>
|
||||
|
||||
## Symlinked sibling repos
|
||||
<ParamField path="skills.workshop.approvalPolicy" type='"pending" | "auto"' default='"pending"'>
|
||||
`pending` requires operator approval before agent-initiated apply, reject, or
|
||||
quarantine. `auto` allows those actions without approval.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.workshop.maxPending" type="number" default="50">
|
||||
Maximum pending and quarantined proposals retained per workspace.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="skills.workshop.maxSkillBytes" type="number" default="40000">
|
||||
Maximum proposal body size in bytes. Proposal descriptions are hard-capped at
|
||||
160 bytes because they appear in discovery and listing output.
|
||||
</ParamField>
|
||||
|
||||
## Symlinked skill roots
|
||||
|
||||
By default, workspace, project-agent, extra-dir, and bundled skill roots are
|
||||
containment boundaries. If a skill folder under `<workspace>/skills` is a
|
||||
symlink that resolves outside `<workspace>/skills`, OpenClaw skips it and logs
|
||||
`Skipping escaped skill path outside its configured root`.
|
||||
containment boundaries. A symlinked skill folder under `<workspace>/skills`
|
||||
that resolves outside the root is skipped with a log message.
|
||||
|
||||
Keep the symlink layout and allow only the trusted target root:
|
||||
To allow an intentional symlink layout, declare the trusted target:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -158,60 +200,72 @@ Keep the symlink layout and allow only the trusted target root:
|
||||
}
|
||||
```
|
||||
|
||||
With this config, a symlink such as
|
||||
`<workspace>/skills/manager -> ~/Projects/manager/skills` is accepted after
|
||||
realpath resolution. `extraDirs` also scans the sibling repo directly, while
|
||||
`allowSymlinkTargets` preserves the symlinked path for existing workspace-skill
|
||||
layouts. Managed `~/.openclaw/skills` and personal `~/.agents/skills`
|
||||
directories already accept skill-directory symlinks because those roots are
|
||||
user-owned local skill-manager surfaces; per-skill `SKILL.md` containment still
|
||||
applies. Keep target entries narrow; do not point at broad roots such as `~` or
|
||||
`~/Projects` unless every skill tree under that root is trusted.
|
||||
With this config, `<workspace>/skills/manager -> ~/Projects/manager/skills` is
|
||||
accepted after realpath resolution. `extraDirs` scans the sibling repo directly;
|
||||
`allowSymlinkTargets` preserves the symlinked path for existing layouts.
|
||||
|
||||
Per-skill fields:
|
||||
Managed `~/.openclaw/skills` and personal `~/.agents/skills` directories
|
||||
already accept skill-directory symlinks (per-skill `SKILL.md` containment still
|
||||
applies).
|
||||
|
||||
- `enabled`: set `false` to disable a skill even if it's bundled/installed.
|
||||
- `env`: environment variables injected for the agent run (only if not already set).
|
||||
- `apiKey`: optional convenience for skills that declare a primary env var.
|
||||
Supports plaintext string or SecretRef object (`{ source, provider, id }`).
|
||||
|
||||
## Notes
|
||||
|
||||
- Keys under `entries` map to the skill name by default. If a skill defines
|
||||
`metadata.openclaw.skillKey`, use that key instead.
|
||||
- Load precedence is `<workspace>/skills` → `<workspace>/.agents/skills` →
|
||||
`~/.agents/skills` → `~/.openclaw/skills` → bundled skills →
|
||||
`skills.load.extraDirs`.
|
||||
- Changes to skills are picked up on the next agent turn when the watcher is enabled.
|
||||
|
||||
### Sandboxed skills and env vars
|
||||
|
||||
When a session is **sandboxed**, skill processes run inside the configured sandbox backend. The sandbox does **not** inherit the host `process.env`.
|
||||
## Sandboxed skills and env vars
|
||||
|
||||
<Warning>
|
||||
Global `env` and `skills.entries.<skill>.env`/`apiKey` apply to **host** runs only. Inside a sandbox they have no effect, so a skill that depends on `GEMINI_API_KEY` will fail with `apiKey not configured` unless the sandbox is given the variable separately.
|
||||
`skills.entries.<skill>.env` and `apiKey` apply to **host** runs only. Inside
|
||||
a sandbox they have no effect — a skill that depends on `GEMINI_API_KEY` will
|
||||
fail with `apiKey not configured` unless the sandbox is given the variable
|
||||
separately.
|
||||
</Warning>
|
||||
|
||||
Use one of:
|
||||
Pass secrets into a Docker sandbox with:
|
||||
|
||||
- `agents.defaults.sandbox.docker.env` for the Docker backend (or per-agent `agents.list[].sandbox.docker.env`).
|
||||
- Bake the env into your custom sandbox image or remote sandbox environment.
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
docker: {
|
||||
env: { GEMINI_API_KEY: "your-key-here" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
For Docker sandboxes, configured `sandbox.docker.env` values become explicit container environment variables. Users with Docker daemon access can inspect them through Docker metadata, so use a mounted secret file, custom image, or another delivery path when that exposure is not acceptable.
|
||||
<Note>
|
||||
Users with Docker daemon access can inspect `sandbox.docker.env` values
|
||||
through Docker metadata. Use a mounted secret file, a custom image, or
|
||||
another delivery path when that exposure is not acceptable.
|
||||
</Note>
|
||||
|
||||
## Loading order reminder
|
||||
|
||||
```text
|
||||
workspace/skills (highest)
|
||||
workspace/.agents/skills
|
||||
~/.agents/skills
|
||||
~/.openclaw/skills
|
||||
bundled skills
|
||||
skills.load.extraDirs (lowest)
|
||||
```
|
||||
|
||||
Changes to skills and config take effect on the next new session when the
|
||||
watcher is enabled, or on the next agent turn when the watcher detects a change.
|
||||
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Skills" href="/tools/skills" icon="puzzle-piece">
|
||||
What skills are and how they load.
|
||||
<Card title="Skills reference" href="/tools/skills" icon="puzzle-piece">
|
||||
What skills are, loading order, gating, and SKILL.md format.
|
||||
</Card>
|
||||
<Card title="Creating skills" href="/tools/creating-skills" icon="hammer">
|
||||
Authoring custom skill packs.
|
||||
Authoring custom workspace skills.
|
||||
</Card>
|
||||
<Card title="Skill Workshop" href="/tools/skill-workshop" icon="flask">
|
||||
Proposal queue for agent-drafted skills.
|
||||
</Card>
|
||||
<Card title="Slash commands" href="/tools/slash-commands" icon="terminal">
|
||||
Native command catalog and chat directives.
|
||||
</Card>
|
||||
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
|
||||
Full `skills` and `agents.skills` schema.
|
||||
Native slash-command catalog and chat directives.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -1,88 +1,94 @@
|
||||
---
|
||||
summary: "Skills: managed vs workspace, gating rules, agent allowlists, and config wiring"
|
||||
title: "Skills"
|
||||
sidebarTitle: "Skills"
|
||||
summary: "Skills teach your agent how to use tools. Learn how they load, how precedence works, and how to configure gating, allowlists, and environment injection."
|
||||
read_when:
|
||||
- Adding or modifying skills
|
||||
- Changing skill gating, allowlists, or load rules
|
||||
- Understanding skill precedence and snapshot behavior
|
||||
title: "Skills"
|
||||
sidebarTitle: "Skills"
|
||||
---
|
||||
|
||||
OpenClaw uses **[AgentSkills](https://agentskills.io)-compatible** skill
|
||||
folders to teach the agent how to use tools. Each skill is a directory
|
||||
containing a `SKILL.md` with YAML frontmatter and instructions. OpenClaw
|
||||
loads bundled skills plus optional local overrides, and filters them at
|
||||
load time based on environment, config, and binary presence.
|
||||
Skills are markdown instruction files that teach the agent how and when to use
|
||||
tools. Each skill lives in a directory containing a `SKILL.md` file with YAML
|
||||
frontmatter and a markdown body. OpenClaw loads bundled skills plus any local
|
||||
overrides, and filters them at load time based on environment, config, and
|
||||
binary presence.
|
||||
|
||||
## Locations and precedence
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Creating skills" href="/tools/creating-skills" icon="hammer">
|
||||
Build and test a custom skill from scratch.
|
||||
</Card>
|
||||
<Card title="Skill Workshop" href="/tools/skill-workshop" icon="flask">
|
||||
Review and approve agent-drafted skill proposals.
|
||||
</Card>
|
||||
<Card title="Skills config" href="/tools/skills-config" icon="gear">
|
||||
Full `skills.*` config schema and agent allowlists.
|
||||
</Card>
|
||||
<Card title="ClawHub" href="/clawhub" icon="cloud">
|
||||
Browse and install community skills.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
OpenClaw loads skills from these sources, **highest precedence first**:
|
||||
## Loading order
|
||||
|
||||
| # | Source | Path |
|
||||
| --- | --------------------- | -------------------------------- |
|
||||
| 1 | Workspace skills | `<workspace>/skills` |
|
||||
OpenClaw loads from these sources, **highest precedence first**. When the same
|
||||
skill name appears in multiple places, the highest source wins.
|
||||
|
||||
| Priority | Source | Path |
|
||||
| ----------- | ---------------------- | --------------------------------------- |
|
||||
| 1 — highest | Workspace skills | `<workspace>/skills` |
|
||||
| 2 | Project agent skills | `<workspace>/.agents/skills` |
|
||||
| 3 | Personal agent skills | `~/.agents/skills` |
|
||||
| 4 | Managed/local skills | `~/.openclaw/skills` |
|
||||
| 4 | Managed / local skills | `~/.openclaw/skills` |
|
||||
| 5 | Bundled skills | shipped with the install |
|
||||
| 6 | Extra skill folders | `skills.load.extraDirs` (config) |
|
||||
| 6 — lowest | Extra directories | `skills.load.extraDirs` + plugin skills |
|
||||
|
||||
If a skill name conflicts, the highest source wins.
|
||||
|
||||
Skill roots can be organized with folders. A skill is discovered when a
|
||||
`SKILL.md` appears under a configured skills root, so these are both valid:
|
||||
Skill roots support grouped layouts. OpenClaw discovers a skill whenever
|
||||
`SKILL.md` appears anywhere under a configured root:
|
||||
|
||||
```text
|
||||
<workspace>/skills/research/SKILL.md
|
||||
<workspace>/skills/personal/research/SKILL.md
|
||||
<workspace>/skills/research/SKILL.md ✓ found as "research"
|
||||
<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"
|
||||
```
|
||||
|
||||
The folder path is only for organization. The skill's visible name, slash
|
||||
command, and allowlist key come from `SKILL.md` frontmatter `name` (or the skill
|
||||
directory name when `name` is missing), so a nested skill with `name: research`
|
||||
is still invoked as `/research`, not `/personal/research`.
|
||||
The folder path is for organization only. The skill's name, slash command, and
|
||||
allowlist key all come from the `name` frontmatter field (or the directory name
|
||||
when `name` is missing).
|
||||
|
||||
Codex CLI's native `$CODEX_HOME/skills` directory is not one of these OpenClaw
|
||||
skill roots. In Codex harness mode, local app-server launches use isolated
|
||||
per-agent Codex homes, so skills in the operator's personal `~/.codex/skills`
|
||||
are not loaded implicitly. Codex-native `.agents` discovery uses inherited
|
||||
`HOME` separately; OpenClaw's own skill roots above already include
|
||||
`~/.agents/skills`. Use `openclaw migrate plan codex` to inventory skills from
|
||||
the Codex home, then `openclaw migrate codex` to choose skill directories with an interactive
|
||||
checkbox prompt before copying them into the current OpenClaw agent workspace.
|
||||
For non-interactive runs, repeat `--skill <name>` for the exact skills to copy.
|
||||
<Note>
|
||||
Codex CLI's native `$CODEX_HOME/skills` directory is **not** an OpenClaw
|
||||
skill root. Use `openclaw migrate plan codex` to inventory those skills, then
|
||||
`openclaw migrate codex` to copy them into your OpenClaw workspace.
|
||||
</Note>
|
||||
|
||||
## Per-agent vs shared skills
|
||||
|
||||
In **multi-agent** setups each agent has its own workspace:
|
||||
In multi-agent setups, each agent has its own workspace. Use the path that
|
||||
matches your desired visibility:
|
||||
|
||||
| Scope | Path | Visible to |
|
||||
| -------------------- | ------------------------------------------- | --------------------------- |
|
||||
| -------------- | ---------------------------- | --------------------------- |
|
||||
| Per-agent | `<workspace>/skills` | Only that agent |
|
||||
| Project-agent | `<workspace>/.agents/skills` | Only that workspace's agent |
|
||||
| Personal-agent | `~/.agents/skills` | All agents on that machine |
|
||||
| Shared managed/local | `~/.openclaw/skills` | All agents on that machine |
|
||||
| Shared extra dirs | `skills.load.extraDirs` (lowest precedence) | All agents on that machine |
|
||||
| Personal-agent | `~/.agents/skills` | All agents on this machine |
|
||||
| Shared managed | `~/.openclaw/skills` | All agents on this machine |
|
||||
| Extra dirs | `skills.load.extraDirs` | All agents on this machine |
|
||||
|
||||
Same name in multiple places → highest source wins. Workspace beats
|
||||
project-agent, beats personal-agent, beats managed/local, beats bundled,
|
||||
beats extra dirs.
|
||||
## Agent allowlists
|
||||
|
||||
## Agent skill allowlists
|
||||
|
||||
Skill **location** and skill **visibility** are separate controls.
|
||||
Location/precedence decides which copy of a same-named skill wins; agent
|
||||
allowlists decide which skills an agent can actually use.
|
||||
Skill **location** (precedence) and skill **visibility** (which agent can use
|
||||
it) are separate controls. Use allowlists to restrict which skills an agent sees,
|
||||
regardless of where they are loaded from.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
skills: ["github", "weather"],
|
||||
skills: ["github", "weather"], // shared baseline
|
||||
},
|
||||
list: [
|
||||
{ id: "writer" }, // inherits github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults entirely
|
||||
{ id: "locked-down", skills: [] }, // no skills
|
||||
],
|
||||
},
|
||||
@@ -91,182 +97,191 @@ allowlists decide which skills an agent can actually use.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Allowlist rules">
|
||||
- Omit `agents.defaults.skills` for unrestricted skills by default.
|
||||
- Omit `agents.defaults.skills` to leave all skills unrestricted by default.
|
||||
- Omit `agents.list[].skills` to inherit `agents.defaults.skills`.
|
||||
- Set `agents.list[].skills: []` for no skills.
|
||||
- A non-empty `agents.list[].skills` list is the **final** set for that
|
||||
agent - it does not merge with defaults.
|
||||
- The effective allowlist applies across prompt building, skill
|
||||
slash-command discovery, sandbox sync, and skill snapshots.
|
||||
- Set `agents.list[].skills: []` to expose no skills for that agent.
|
||||
- A non-empty `agents.list[].skills` list is the **final** set — it does not
|
||||
merge with defaults.
|
||||
- The effective allowlist applies across prompt building, slash-command
|
||||
discovery, sandbox sync, and skill snapshots.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Plugins and skills
|
||||
|
||||
Plugins can ship their own skills by listing `skills` directories in
|
||||
`openclaw.plugin.json` (paths relative to the plugin root). Plugin skills
|
||||
load when the plugin is enabled. This is the right place for tool-specific
|
||||
operating guides that are too long for the tool description but should be
|
||||
available whenever the plugin is installed - for example, the browser
|
||||
plugin ships a `browser-automation` skill for multi-step browser control.
|
||||
`openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load
|
||||
when the plugin is enabled — for example, the browser plugin ships a
|
||||
`browser-automation` skill for multi-step browser control.
|
||||
|
||||
Plugin skill directories are merged into the same low-precedence path as
|
||||
`skills.load.extraDirs`, so a same-named bundled, managed, agent, or
|
||||
workspace skill overrides them. You can gate them via
|
||||
`metadata.openclaw.requires.config` on the plugin's config entry.
|
||||
Plugin skill directories merge at the same low-precedence level as
|
||||
`skills.load.extraDirs`, so a same-named bundled, managed, agent, or workspace
|
||||
skill overrides them. Gate them via `metadata.openclaw.requires.config` on the
|
||||
plugin's config entry.
|
||||
|
||||
See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for
|
||||
the tool surface those skills teach.
|
||||
See [Plugins](/tools/plugin) and [Tools](/tools) for the full plugin system.
|
||||
|
||||
## Skill Workshop
|
||||
|
||||
[Skill Workshop](/tools/skill-workshop) is the governed path for
|
||||
agent-generated or reviewed skill creation and improvement. It turns reusable
|
||||
work into a pending proposal, scans and hashes the proposal bundle, supports
|
||||
review and revision, and writes the final `SKILL.md` only after apply.
|
||||
[Skill Workshop](/tools/skill-workshop) is a proposal queue between the agent
|
||||
and your active skill files. When the agent spots reusable work, it drafts a
|
||||
proposal instead of writing directly to `SKILL.md`. You review and approve
|
||||
before anything changes.
|
||||
|
||||
Use it when an agent or operator wants to capture reusable work without
|
||||
silently mutating active workspace skills.
|
||||
```bash
|
||||
openclaw skills workshop list
|
||||
openclaw skills workshop inspect <proposal-id>
|
||||
openclaw skills workshop apply <proposal-id>
|
||||
```
|
||||
|
||||
## ClawHub (install and sync)
|
||||
See [Skill Workshop](/tools/skill-workshop) for the full lifecycle, CLI
|
||||
reference, and configuration.
|
||||
|
||||
[ClawHub](https://clawhub.ai) is the public skills registry for OpenClaw.
|
||||
Use native `openclaw skills` commands for discover/install/update, or the
|
||||
separate `clawhub` CLI for publish/sync workflows. Full guide:
|
||||
[ClawHub](/clawhub).
|
||||
## Installing from ClawHub
|
||||
|
||||
[ClawHub](https://clawhub.ai) is the public skills registry. Use
|
||||
`openclaw skills` commands for install and update, or the `clawhub` CLI for
|
||||
publish and sync.
|
||||
|
||||
| Action | Command |
|
||||
| -------------------------------------- | ------------------------------------------------------ |
|
||||
| Install a ClawHub skill into workspace | `openclaw skills install <skill-slug>` |
|
||||
| Install a Git skill into workspace | `openclaw skills install git:owner/repo@ref` |
|
||||
| Install a local skill into workspace | `openclaw skills install ./path/to/skill --as my-tool` |
|
||||
| Install a skill for all local agents | `openclaw skills install <skill-slug> --global` |
|
||||
| Update all workspace-installed skills | `openclaw skills update --all` |
|
||||
| Update a single shared managed skill | `openclaw skills update <skill-slug> --global` |
|
||||
| Update all shared managed/local skills | `openclaw skills update --all --global` |
|
||||
| Verify a ClawHub skill | `openclaw skills verify <skill-slug>` |
|
||||
| Print the generated Skill Card | `openclaw skills verify <skill-slug> --card` |
|
||||
| Sync (scan + publish updates) | `clawhub sync --all` |
|
||||
| ---------------------------------- | ------------------------------------------------------ |
|
||||
| Install a skill into the workspace | `openclaw skills install <slug>` |
|
||||
| Install from a Git repository | `openclaw skills install git:owner/repo@ref` |
|
||||
| Install a local skill directory | `openclaw skills install ./path/to/skill --as my-tool` |
|
||||
| Install for all local agents | `openclaw skills install <slug> --global` |
|
||||
| Update all workspace skills | `openclaw skills update --all` |
|
||||
| Update a shared managed skill | `openclaw skills update <slug> --global` |
|
||||
| Update all shared managed skills | `openclaw skills update --all --global` |
|
||||
| Verify a skill's trust envelope | `openclaw skills verify <slug>` |
|
||||
| Print the generated Skill Card | `openclaw skills verify <slug> --card` |
|
||||
| Publish / sync via ClawHub CLI | `clawhub sync --all` |
|
||||
|
||||
Native `openclaw skills install` installs into the active workspace
|
||||
`skills/` directory by default. Add `--global` to install into the shared
|
||||
managed/local directory (`~/.openclaw/skills` by default), which is visible to
|
||||
all local agents unless agent skill allowlists narrow visibility. The separate
|
||||
`clawhub` CLI also installs into `./skills` under your current working
|
||||
directory (or falls back to the configured OpenClaw workspace). OpenClaw picks
|
||||
that up as `<workspace>/skills` on the next session.
|
||||
Configured skill roots also support grouped layouts, such as
|
||||
`skills/<group>/<skill>/SKILL.md`, so related third-party skills can be kept
|
||||
under shared folders without broad recursive scanning. Use flat frontmatter
|
||||
names when grouping, for example `skills/imported/research/SKILL.md` with
|
||||
`name: research`.
|
||||
<AccordionGroup>
|
||||
<Accordion title="Install details">
|
||||
`openclaw skills install` installs into the active workspace `skills/`
|
||||
directory by default. Add `--global` to install into the shared
|
||||
`~/.openclaw/skills` directory, visible to all local agents unless agent
|
||||
allowlists narrow it.
|
||||
|
||||
Git and local directory installs expect a `SKILL.md` at the source root. The
|
||||
install slug comes from `SKILL.md` frontmatter `name` when it is a valid slug,
|
||||
then falls back to the source directory or repository name. Use `--as <slug>` to
|
||||
override the inferred slug. `--version` applies only to ClawHub installs. Skill
|
||||
installs do not support npm package specs or zip/archive paths. `openclaw skills
|
||||
update` updates ClawHub-tracked installs only; reinstall Git or local sources to
|
||||
refresh them.
|
||||
Git and local installs expect `SKILL.md` at the source root. The slug comes
|
||||
from `SKILL.md` frontmatter `name` when valid, then falls back to the
|
||||
directory or repository name. Use `--as <slug>` to override.
|
||||
`openclaw skills update` tracks ClawHub installs only — reinstall Git or
|
||||
local sources to refresh them.
|
||||
|
||||
Use `openclaw skills verify <slug>` to ask ClawHub for the skill's
|
||||
`clawhub.skill.verify.v1` trust envelope. Output is JSON by default; use
|
||||
`--card` to print the generated Skill Card Markdown. Installed ClawHub skills
|
||||
verify against the version and registry recorded in `.clawhub/origin.json`;
|
||||
`--version` and `--tag` override only the version selector. The command exits
|
||||
non-zero when ClawHub marks verification as failed. A generated `skill-card.md`
|
||||
may be present in installed bundles, but OpenClaw treats it as ClawHub-provided
|
||||
metadata and does not use it as local model instructions or a local hash gate.
|
||||
</Accordion>
|
||||
<Accordion title="Verification and security scanning">
|
||||
`openclaw skills verify <slug>` asks ClawHub for the skill's
|
||||
`clawhub.skill.verify.v1` trust envelope. Installed ClawHub skills verify
|
||||
against the version and registry recorded in `.clawhub/origin.json`.
|
||||
|
||||
Gateway clients that need private, non-ClawHub delivery can stage a zip skill
|
||||
archive with `skills.upload.begin`, `skills.upload.chunk`, and
|
||||
`skills.upload.commit`, then install the committed upload with
|
||||
`skills.install({ source: "upload", uploadId, slug, force?, sha256? })`. This is
|
||||
an explicit admin upload path for trusted clients, not the normal
|
||||
`openclaw skills install <slug>` or ClawHub install flow. It is off by default
|
||||
and only works when `skills.install.allowUploadedArchives: true` is set in
|
||||
`openclaw.json`. Upload mode still installs into the default agent workspace
|
||||
`skills/<slug>` directory; the archive's internal folder name is ignored for the
|
||||
final install target.
|
||||
ClawHub skill pages expose the latest security scan state before install,
|
||||
with detail pages for VirusTotal, ClawScan, and static analysis. The
|
||||
command exits non-zero when ClawHub marks verification as failed. Publishers
|
||||
recover false positives through the ClawHub dashboard or
|
||||
`clawhub skill rescan <slug>`.
|
||||
|
||||
ClawHub skill pages expose the latest security scan state before install,
|
||||
with scanner detail pages for VirusTotal, ClawScan, and static analysis.
|
||||
`openclaw skills install <slug>` remains only the install path; publishers
|
||||
recover false positives through the ClawHub dashboard or
|
||||
`clawhub skill rescan <slug>`.
|
||||
</Accordion>
|
||||
<Accordion title="Private archive installs">
|
||||
Gateway clients that need non-ClawHub delivery can stage a zip skill archive
|
||||
with `skills.upload.begin`, `skills.upload.chunk`, and `skills.upload.commit`,
|
||||
then install with `skills.install({ source: "upload", ... })`. This path is
|
||||
off by default and requires `skills.install.allowUploadedArchives: true` in
|
||||
`openclaw.json`. Normal ClawHub installs never need that setting.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Security
|
||||
|
||||
<Warning>
|
||||
Treat third-party skills as **untrusted code**. Read them before enabling.
|
||||
Prefer sandboxed runs for untrusted inputs and risky tools. See
|
||||
[Sandboxing](/gateway/sandboxing) for the agent-side controls.
|
||||
Treat third-party skills as **untrusted code**. Read them before enabling.
|
||||
Prefer sandboxed runs for untrusted inputs and risky tools. See
|
||||
[Sandboxing](/gateway/sandboxing) for agent-side controls.
|
||||
</Warning>
|
||||
|
||||
- Workspace, project-agent, and extra-dir skill discovery only accepts skill roots whose resolved realpath stays inside the configured root unless `skills.load.allowSymlinkTargets` explicitly trusts a target root. Bundled skills always stay contained. Managed `~/.openclaw/skills` and personal `~/.agents/skills` roots may contain symlinked skill folders installed by ClawHub or another local skill manager, but every `SKILL.md` realpath must still stay inside its resolved skill directory.
|
||||
- Nested discovery is bounded. OpenClaw scans grouped skill folders under
|
||||
skills roots such as `<workspace>/skills`, `<workspace>/.agents/skills`,
|
||||
`~/.agents/skills`, and `~/.openclaw/skills`, but skips hidden directories,
|
||||
`node_modules`, oversized `SKILL.md` files, escaped symlinks, and suspiciously
|
||||
large directory trees.
|
||||
- Gateway private archive installs are off by default. When explicitly enabled,
|
||||
they require a committed zip upload containing `SKILL.md` and reuse the same
|
||||
archive extraction, path traversal, symlink, force, and rollback protections as
|
||||
ClawHub skill installs. They are gated by
|
||||
`skills.install.allowUploadedArchives`; normal ClawHub installs do not require
|
||||
that setting.
|
||||
- Gateway-backed skill dependency installs (`skills.install`, onboarding, and the Skills settings UI) run the built-in dangerous-code scanner before executing installer metadata. `critical` findings block by default unless the caller explicitly sets the dangerous override; suspicious findings still warn only.
|
||||
- `openclaw skills install <slug>` is different — it downloads a ClawHub skill
|
||||
folder into the workspace, or into shared managed/local skills with
|
||||
`--global`, and does not use the installer-metadata path above. Git and local
|
||||
directory installs copy a trusted `SKILL.md` directory into the same skills
|
||||
root, but are not tracked by `openclaw skills update`.
|
||||
- `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process for that agent turn (not the sandbox). Keep secrets out of prompts and logs.
|
||||
<AccordionGroup>
|
||||
<Accordion title="Path containment">
|
||||
Workspace, project-agent, and extra-dir skill discovery only accepts skill
|
||||
roots whose resolved realpath stays inside the configured root, unless
|
||||
`skills.load.allowSymlinkTargets` explicitly trusts a target root.
|
||||
Managed `~/.openclaw/skills` and personal `~/.agents/skills` may contain
|
||||
symlinked skill folders, but every `SKILL.md` realpath must still stay
|
||||
inside its resolved skill directory.
|
||||
</Accordion>
|
||||
<Accordion title="Scan and scan overrides">
|
||||
Gateway-backed skill installs (onboarding, Skills settings UI) run the
|
||||
built-in dangerous-code scanner before executing installer metadata.
|
||||
`critical` findings block by default; `suspicious` findings warn only.
|
||||
`openclaw skills install <slug>` downloads a ClawHub skill folder directly
|
||||
and does not use the installer-metadata scanner.
|
||||
</Accordion>
|
||||
<Accordion title="Secret injection scope">
|
||||
`skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the
|
||||
**host** process for that agent turn only — not into the sandbox. Keep
|
||||
secrets out of prompts and logs.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
For a broader threat model and checklists, see [Security](/gateway/security).
|
||||
For the broader threat model and security checklists, see
|
||||
[Security](/gateway/security).
|
||||
|
||||
## SKILL.md format
|
||||
|
||||
`SKILL.md` must include at least:
|
||||
Every skill needs at minimum a `name` and `description` in the frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: image-lab
|
||||
description: Generate or edit images via a provider-backed image workflow
|
||||
---
|
||||
|
||||
When the user asks to generate an image, use the `image_generate` tool...
|
||||
```
|
||||
|
||||
OpenClaw follows the AgentSkills spec for layout/intent. The parser used
|
||||
by the embedded agent supports **single-line** frontmatter keys only;
|
||||
`metadata` should be a **single-line JSON object**. Use `{baseDir}` in
|
||||
instructions to reference the skill folder path.
|
||||
<Note>
|
||||
OpenClaw follows the [AgentSkills](https://agentskills.io) spec. The
|
||||
frontmatter parser supports **single-line keys only** — `metadata` must be a
|
||||
single-line JSON object. Use `{baseDir}` in the body to reference the skill
|
||||
folder path.
|
||||
</Note>
|
||||
|
||||
### Optional frontmatter keys
|
||||
|
||||
<ParamField path="homepage" type="string">
|
||||
URL surfaced as "Website" in the macOS Skills UI. Also supported via `metadata.openclaw.homepage`.
|
||||
URL shown as "Website" in the macOS Skills UI. Also supported via
|
||||
`metadata.openclaw.homepage`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="user-invocable" type="boolean" default="true">
|
||||
When `true`, the skill is exposed as a user slash command.
|
||||
When `true`, the skill is exposed as a user-invocable slash command.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="disable-model-invocation" type="boolean" default="false">
|
||||
When `true`, OpenClaw keeps the skill's instructions out of the agent's normal
|
||||
prompt. The skill is still installed and can still be run explicitly as a
|
||||
slash command when `user-invocable` is also `true`.
|
||||
prompt. The skill is still available as a slash command when `user-invocable`
|
||||
is also `true`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="command-dispatch" type='"tool"'>
|
||||
When set to `tool`, the slash command bypasses the model and dispatches directly to a tool.
|
||||
When set to `tool`, the slash command bypasses the model and dispatches
|
||||
directly to a registered tool.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="command-tool" type="string">
|
||||
Tool name to invoke when `command-dispatch: tool` is set.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="command-arg-mode" type='"raw"' default="raw">
|
||||
For tool dispatch, forwards the raw args string to the tool (no core parsing). The tool is invoked with `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`.
|
||||
For tool dispatch, forwards the raw args string to the tool with no
|
||||
core parsing. The tool receives
|
||||
`{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`.
|
||||
</ParamField>
|
||||
|
||||
## Gating (load-time filters)
|
||||
## Gating
|
||||
|
||||
OpenClaw filters skills at load time using `metadata` (single-line JSON):
|
||||
OpenClaw filters skills at load time using `metadata.openclaw` (single-line
|
||||
JSON in the frontmatter). A skill with no `metadata.openclaw` block is always
|
||||
eligible unless explicitly disabled.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -283,57 +298,57 @@ metadata:
|
||||
---
|
||||
```
|
||||
|
||||
Fields under `metadata.openclaw`:
|
||||
|
||||
<ParamField path="always" type="boolean">
|
||||
When `true`, always include the skill (skip other gates).
|
||||
When `true`, always include the skill and skip all other gates.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="emoji" type="string">
|
||||
Optional emoji used by the macOS Skills UI.
|
||||
Optional emoji shown in the macOS Skills UI.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="homepage" type="string">
|
||||
Optional URL shown as "Website" in the macOS Skills UI.
|
||||
</ParamField>
|
||||
<ParamField path="os" type='"darwin" | "linux" | "win32"' >
|
||||
Optional list of platforms. If set, the skill is only eligible on those OSes.
|
||||
|
||||
<ParamField path="os" type='"darwin" | "linux" | "win32"'>
|
||||
Platform filter. When set, the skill is only eligible on the listed OSes.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="requires.bins" type="string[]">
|
||||
Each must exist on `PATH`.
|
||||
Each binary must exist on `PATH`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="requires.anyBins" type="string[]">
|
||||
At least one must exist on `PATH`.
|
||||
At least one binary must exist on `PATH`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="requires.env" type="string[]">
|
||||
Env var must exist or be provided in config.
|
||||
Each env var must exist in the process or be provided via config.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="requires.config" type="string[]">
|
||||
List of `openclaw.json` paths that must be truthy.
|
||||
Each `openclaw.json` path must be truthy.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="primaryEnv" type="string">
|
||||
Env var name associated with `skills.entries.<name>.apiKey`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="install" type="object[]">
|
||||
Optional installer specs used by the macOS Skills UI (brew/node/go/uv/download).
|
||||
Optional installer specs used by the macOS Skills UI (brew / node / go / uv / download).
|
||||
</ParamField>
|
||||
|
||||
If no `metadata.openclaw` is present, the skill is always eligible (unless
|
||||
disabled in config or blocked by `skills.allowBundled` for bundled skills).
|
||||
|
||||
<Note>
|
||||
Legacy `metadata.clawdbot` blocks are still accepted when
|
||||
`metadata.openclaw` is absent, so older installed skills keep their
|
||||
dependency gates and installer hints. New and updated skills should use
|
||||
`metadata.openclaw`.
|
||||
Legacy `metadata.clawdbot` blocks are still accepted when
|
||||
`metadata.openclaw` is absent, so older installed skills keep their
|
||||
dependency gates and installer hints. New skills should use
|
||||
`metadata.openclaw`.
|
||||
</Note>
|
||||
|
||||
### Sandboxing notes
|
||||
|
||||
- `requires.bins` is checked on the **host** at skill load time.
|
||||
- If an agent is sandboxed, the binary must also exist **inside the container**. Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image). `setupCommand` runs once after the container is created. Package installs also require network egress, a writable root FS, and a root user in the sandbox.
|
||||
- Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI in the sandbox container to run there.
|
||||
|
||||
### Installer specs
|
||||
|
||||
Installer specs tell the macOS Skills UI how to install a dependency:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: gemini
|
||||
@@ -361,29 +376,41 @@ metadata:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Installer selection rules">
|
||||
- If multiple installers are listed, the gateway picks a single preferred option (brew when available, otherwise node).
|
||||
- If all installers are `download`, OpenClaw lists each entry so you can see the available artifacts.
|
||||
- Installer specs can include `os: ["darwin"|"linux"|"win32"]` to filter options by platform.
|
||||
- Node installs honor `skills.install.nodeManager` in `openclaw.json` (default: npm; options: npm/pnpm/yarn/bun). This only affects skill installs; the Gateway runtime should still be Node - Bun is not recommended for WhatsApp/Telegram.
|
||||
- Gateway-backed installer selection is preference-driven: when install specs mix kinds, OpenClaw prefers Homebrew when `skills.install.preferBrew` is enabled and `brew` exists, then `uv`, then the configured node manager, then other fallbacks like `go` or `download`.
|
||||
- If every install spec is `download`, OpenClaw surfaces all download options instead of collapsing to one preferred installer.
|
||||
|
||||
- When multiple installers are listed, the gateway picks one preferred
|
||||
option (brew when available, otherwise node).
|
||||
- If all installers are `download`, OpenClaw lists each entry so you can
|
||||
see all available artifacts.
|
||||
- Specs can include `os: ["darwin"|"linux"|"win32"]` to filter by platform.
|
||||
- Node installs honor `skills.install.nodeManager` in `openclaw.json`
|
||||
(default: npm; options: npm / pnpm / yarn / bun). This only affects skill
|
||||
installs; the Gateway runtime should still be Node.
|
||||
- Gateway installer preference: Homebrew → uv → configured node manager →
|
||||
go → download.
|
||||
</Accordion>
|
||||
<Accordion title="Per-installer details">
|
||||
- **Homebrew installs:** OpenClaw does not auto-install Homebrew or translate
|
||||
brew formulas into system package manager commands. In Linux containers
|
||||
without `brew`, onboarding hides brew-only dependency installers; use a
|
||||
custom image or install the dependency manually before enabling that skill.
|
||||
- **Go installs:** if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew's `bin` when possible.
|
||||
- **Download installs:** `url` (required), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (default: auto when archive detected), `stripComponents`, `targetDir` (default: `~/.openclaw/tools/<skillKey>`).
|
||||
|
||||
- **Homebrew:** OpenClaw does not auto-install Homebrew or translate brew
|
||||
formulas into system package commands. In Linux containers without
|
||||
`brew`, brew-only installers are hidden; use a custom image or install
|
||||
the dependency manually.
|
||||
- **Go:** if `go` is missing and `brew` is available, the gateway installs
|
||||
Go via Homebrew first and sets `GOBIN` to Homebrew's `bin`.
|
||||
- **Download:** `url` (required), `archive` (`tar.gz` | `tar.bz2` | `zip`),
|
||||
`extract` (default: auto when archive detected), `stripComponents`,
|
||||
`targetDir` (default: `~/.openclaw/tools/<skillKey>`).
|
||||
</Accordion>
|
||||
<Accordion title="Sandboxing notes">
|
||||
`requires.bins` is checked on the **host** at skill load time. If an agent
|
||||
runs in a sandbox, the binary must also exist **inside the container**.
|
||||
Install it via `agents.defaults.sandbox.docker.setupCommand` or a custom
|
||||
image. `setupCommand` runs once after container creation and requires
|
||||
network egress, a writable root FS, and a root user in the sandbox.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Config overrides
|
||||
|
||||
Bundled and managed skills can be toggled and supplied with env values
|
||||
under `skills.entries` in `~/.openclaw/openclaw.json`:
|
||||
Toggle and configure bundled or managed skills under `skills.entries` in
|
||||
`~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -391,10 +418,8 @@ under `skills.entries` in `~/.openclaw/openclaw.json`:
|
||||
entries: {
|
||||
"image-lab": {
|
||||
enabled: true,
|
||||
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
|
||||
env: {
|
||||
GEMINI_API_KEY: "GEMINI_KEY_HERE",
|
||||
},
|
||||
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
|
||||
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
|
||||
config: {
|
||||
endpoint: "https://example.invalid",
|
||||
model: "nano-pro",
|
||||
@@ -408,81 +433,92 @@ under `skills.entries` in `~/.openclaw/openclaw.json`:
|
||||
```
|
||||
|
||||
<ParamField path="enabled" type="boolean">
|
||||
`false` disables the skill even if it is bundled or installed.
|
||||
The bundled `coding-agent` skill is opt-in: set
|
||||
`skills.entries.coding-agent.enabled: true` before exposing it to agents,
|
||||
then make sure one of `claude`, `codex`, `opencode`, or another supported CLI is installed and
|
||||
authenticated for its own CLI.
|
||||
</ParamField>
|
||||
<ParamField path="apiKey" type='string | { source, provider, id }'>
|
||||
Convenience for skills that declare `metadata.openclaw.primaryEnv`. Supports plaintext or SecretRef.
|
||||
</ParamField>
|
||||
<ParamField path="env" type="Record<string, string>">
|
||||
Injected only if the variable is not already set in the process.
|
||||
</ParamField>
|
||||
<ParamField path="config" type="object">
|
||||
Optional bag for custom per-skill fields. Custom keys must live here.
|
||||
</ParamField>
|
||||
<ParamField path="allowBundled" type="string[]">
|
||||
Optional allowlist for **bundled** skills only. If set, only bundled skills in the list are eligible (managed/workspace skills unaffected).
|
||||
`false` disables the skill even when bundled or installed. The `coding-agent`
|
||||
bundled skill is opt-in — set `skills.entries.coding-agent.enabled: true`
|
||||
and ensure one of `claude`, `codex`, `opencode`, or another supported CLI
|
||||
is installed and authenticated.
|
||||
</ParamField>
|
||||
|
||||
If the skill name contains hyphens, quote the key (JSON5 allows quoted
|
||||
keys). Config keys match the **skill name** by default - if a skill
|
||||
defines `metadata.openclaw.skillKey`, use that key under `skills.entries`.
|
||||
<ParamField path="apiKey" type='string | { source, provider, id }'>
|
||||
Convenience field for skills that declare `metadata.openclaw.primaryEnv`.
|
||||
Supports a plaintext string or a SecretRef object.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="env" type="Record<string, string>">
|
||||
Environment variables injected for the agent run. Only injected when the
|
||||
variable is not already set in the process.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="config" type="object">
|
||||
Optional bag for custom per-skill configuration fields.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="allowBundled" type="string[]">
|
||||
Optional allowlist for **bundled** skills only. When set, only bundled skills
|
||||
in the list are eligible. Managed and workspace skills are unaffected.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
For stock image generation/editing inside OpenClaw, use the core
|
||||
`image_generate` tool with `agents.defaults.imageGenerationModel` instead
|
||||
of a bundled skill. Skill examples here are for custom or third-party
|
||||
workflows. For native image analysis use the `image` tool with
|
||||
`agents.defaults.imageModel`. If you pick `openai/*`, `google/*`,
|
||||
`fal/*`, or another provider-specific image model, add that provider's
|
||||
auth/API key too.
|
||||
Config keys match the **skill name** by default. If a skill defines
|
||||
`metadata.openclaw.skillKey`, use that key under `skills.entries`. Quote
|
||||
hyphenated names: JSON5 allows quoted keys.
|
||||
</Note>
|
||||
|
||||
## Environment injection
|
||||
|
||||
When an agent run starts, OpenClaw:
|
||||
|
||||
1. Reads skill metadata.
|
||||
2. Applies `skills.entries.<key>.env` and `skills.entries.<key>.apiKey` to `process.env`.
|
||||
3. Builds the system prompt with **eligible** skills.
|
||||
4. Restores the original environment after the run ends.
|
||||
<Steps>
|
||||
<Step title="Reads skill metadata">
|
||||
OpenClaw resolves the effective skill list for the agent, applying gating
|
||||
rules, allowlists, and config overrides.
|
||||
</Step>
|
||||
<Step title="Injects env and API keys">
|
||||
`skills.entries.<key>.env` and `skills.entries.<key>.apiKey` are applied to
|
||||
`process.env` for the duration of the run.
|
||||
</Step>
|
||||
<Step title="Builds the system prompt">
|
||||
Eligible skills are compiled into a compact XML block and injected into the
|
||||
system prompt.
|
||||
</Step>
|
||||
<Step title="Restores the environment">
|
||||
After the run ends, the original environment is restored.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Environment injection is **scoped to the agent run**, not a global shell
|
||||
environment.
|
||||
<Warning>
|
||||
Env injection is scoped to the **host** agent run, not the sandbox. Inside a
|
||||
sandbox, `env` and `apiKey` have no effect. See
|
||||
[Skills config](/tools/skills-config#sandboxed-skills-and-env-vars) for how
|
||||
to pass secrets into sandboxed runs.
|
||||
</Warning>
|
||||
|
||||
For the bundled `claude-cli` backend, OpenClaw also materializes the same
|
||||
eligible snapshot as a temporary Claude Code plugin and passes it with
|
||||
`--plugin-dir`. Claude Code can then use its native skill resolver while
|
||||
OpenClaw still owns precedence, per-agent allowlists, gating, and
|
||||
`skills.entries.*` env/API key injection. Other CLI backends use the
|
||||
prompt catalog only.
|
||||
eligible skill snapshot as a temporary Claude Code plugin and passes it via
|
||||
`--plugin-dir`. Other CLI backends use the prompt catalog only.
|
||||
|
||||
## Snapshots and refresh
|
||||
|
||||
OpenClaw snapshots the eligible skills **when a session starts** and
|
||||
reuses that list for subsequent turns in the same session. Changes to
|
||||
skills or config take effect on the next new session.
|
||||
OpenClaw snapshots eligible skills **when a session starts** and reuses that
|
||||
list for all subsequent turns in the session. Changes to skills or config take
|
||||
effect on the next new session.
|
||||
|
||||
Skills can refresh mid-session in two cases:
|
||||
Skills refresh mid-session in two cases:
|
||||
|
||||
- The skills watcher is enabled.
|
||||
- A new eligible remote node appears.
|
||||
- The skills watcher detects a `SKILL.md` change.
|
||||
- A new eligible remote node connects.
|
||||
|
||||
Think of this as a **hot reload**: the refreshed list is picked up on the
|
||||
next agent turn. If the effective agent skill allowlist changes for that
|
||||
session, OpenClaw refreshes the snapshot so visible skills stay aligned
|
||||
with the current agent.
|
||||
The refreshed list is picked up on the next agent turn. If the effective agent
|
||||
allowlist changes, OpenClaw refreshes the snapshot to keep visible skills
|
||||
aligned.
|
||||
|
||||
### Skills watcher
|
||||
<AccordionGroup>
|
||||
<Accordion title="Skills watcher">
|
||||
By default, OpenClaw watches skill folders and bumps the snapshot when
|
||||
`SKILL.md` files change. Configure under `skills.load`:
|
||||
|
||||
By default, OpenClaw watches skill folders and bumps the skills snapshot
|
||||
when `SKILL.md` files change. Configure under `skills.load`:
|
||||
|
||||
```json5
|
||||
{
|
||||
```json5
|
||||
{
|
||||
skills: {
|
||||
load: {
|
||||
extraDirs: ["~/Projects/agent-scripts/skills"],
|
||||
@@ -491,71 +527,61 @@ when `SKILL.md` files change. Configure under `skills.load`:
|
||||
watchDebounceMs: 250,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
Use `allowSymlinkTargets` for intentional workspace, project-agent, or extra-dir
|
||||
layouts where a skill root contains a symlink, for example
|
||||
`<workspace>/skills/manager -> ~/Projects/manager/skills`. Managed
|
||||
`~/.openclaw/skills` and personal `~/.agents/skills` can follow skill-directory
|
||||
symlinks from local skill managers by default, but the target list is still
|
||||
matched after realpath resolution and should stay narrow when configured.
|
||||
Use `allowSymlinkTargets` for intentional symlinked layouts where a skill
|
||||
root symlink points outside the configured root, for example
|
||||
`<workspace>/skills/manager -> ~/Projects/manager/skills`.
|
||||
|
||||
The watcher covers nested `SKILL.md` files under grouped skill roots. Adding or
|
||||
editing `skills/personal/foo/SKILL.md` refreshes the snapshot the same way as
|
||||
editing `skills/foo/SKILL.md`.
|
||||
</Accordion>
|
||||
<Accordion title="Remote macOS nodes (Linux gateway)">
|
||||
If the Gateway runs on Linux but a **macOS node** is connected with
|
||||
`system.run` allowed, OpenClaw can treat macOS-only skills as eligible when
|
||||
the required binaries are present on that node. The agent should run those
|
||||
skills via the `exec` tool with `host=node`.
|
||||
|
||||
### Remote macOS nodes (Linux gateway)
|
||||
Offline nodes do **not** make remote-only skills visible. If a node stops
|
||||
answering bin probes, OpenClaw clears its cached bin matches.
|
||||
|
||||
If the Gateway runs on Linux but a **macOS node** is connected with
|
||||
`system.run` allowed (Exec approvals security not set to `deny`),
|
||||
OpenClaw can treat macOS-only skills as eligible when the required
|
||||
binaries are present on that node. The agent should execute those skills
|
||||
via the `exec` tool with `host=node`.
|
||||
|
||||
This relies on the node reporting its command support and on a bin probe
|
||||
via `system.which` or `system.run`. Offline nodes do **not** make
|
||||
remote-only skills visible. If a connected node stops answering bin
|
||||
probes, OpenClaw clears its cached bin matches so agents no longer see
|
||||
skills that cannot currently run there.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Token impact
|
||||
|
||||
When skills are eligible, OpenClaw injects a compact XML list of available
|
||||
skills into the system prompt (via `formatSkillsForPrompt` in
|
||||
`session runtime`). The cost is deterministic:
|
||||
|
||||
- **Base overhead** (only when ≥1 skill): 195 characters.
|
||||
- **Per skill:** 97 characters + the length of the XML-escaped `<name>`, `<description>`, and `<location>` values.
|
||||
|
||||
Formula (characters):
|
||||
When skills are eligible, OpenClaw injects a compact XML block into the system
|
||||
prompt. The cost is deterministic:
|
||||
|
||||
```text
|
||||
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
|
||||
total = 195 + Σ (97 + len(name) + len(description) + len(filepath))
|
||||
```
|
||||
|
||||
XML escaping expands `& < > " '` into entities (`&`, `<`, etc.),
|
||||
increasing length. Token counts vary by model tokenizer. A rough
|
||||
OpenAI-style estimate is ~4 chars/token, so **97 chars ≈ 24 tokens** per
|
||||
skill plus your actual field lengths.
|
||||
- **Base overhead** (only when ≥ 1 skill): ~195 characters
|
||||
- **Per skill:** ~97 characters + your `name`, `description`, and `location` field lengths
|
||||
- XML escaping expands `& < > " '` into entities, adding a few characters per occurrence
|
||||
- At ~4 chars/token, 97 chars ≈ 24 tokens per skill before field lengths
|
||||
|
||||
## Managed skills lifecycle
|
||||
|
||||
OpenClaw ships a baseline set of skills as **bundled skills** with the
|
||||
install (npm package or OpenClaw.app). `~/.openclaw/skills` exists for
|
||||
local overrides - for example, pinning or patching a skill without
|
||||
changing the bundled copy. Workspace skills are user-owned and override
|
||||
both on name conflicts.
|
||||
|
||||
## Looking for more skills?
|
||||
|
||||
Browse [https://clawhub.ai](https://clawhub.ai). Full configuration
|
||||
schema: [Skills config](/tools/skills-config).
|
||||
Keep descriptions short and descriptive to minimize prompt overhead.
|
||||
|
||||
## Related
|
||||
|
||||
- [ClawHub](/clawhub) - public skills registry
|
||||
- [Creating skills](/tools/creating-skills) - building custom skills
|
||||
- [Plugins](/tools/plugin) - plugin system overview
|
||||
- [Skills config](/tools/skills-config) - skill configuration reference
|
||||
- [Slash commands](/tools/slash-commands) - all available slash commands
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Creating skills" href="/tools/creating-skills" icon="hammer">
|
||||
Step-by-step guide to authoring a custom skill.
|
||||
</Card>
|
||||
<Card title="Skill Workshop" href="/tools/skill-workshop" icon="flask">
|
||||
Proposal queue for agent-drafted skills.
|
||||
</Card>
|
||||
<Card title="Skills config" href="/tools/skills-config" icon="gear">
|
||||
Full `skills.*` config schema and agent allowlists.
|
||||
</Card>
|
||||
<Card title="Slash commands" href="/tools/slash-commands" icon="terminal">
|
||||
How skill slash commands are registered and routed.
|
||||
</Card>
|
||||
<Card title="ClawHub" href="/clawhub" icon="cloud">
|
||||
Browse and publish skills on the public registry.
|
||||
</Card>
|
||||
<Card title="Plugins" href="/tools/plugin" icon="plug">
|
||||
Plugins can ship skills alongside the tools they document.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -1,40 +1,55 @@
|
||||
---
|
||||
summary: "Slash commands: text vs native, config, and supported commands"
|
||||
title: "Slash commands"
|
||||
sidebarTitle: "Slash commands"
|
||||
summary: "All available slash commands, directives, and inline shortcuts — configuration, routing, and per-surface behavior."
|
||||
read_when:
|
||||
- Using or configuring chat commands
|
||||
- Debugging command routing or permissions
|
||||
title: "Slash commands"
|
||||
sidebarTitle: "Slash commands"
|
||||
- Understanding how skill commands are registered
|
||||
---
|
||||
|
||||
Commands are handled by the Gateway. Most commands must be sent as a **standalone** message that starts with `/`. The host-only bash chat command uses `! <cmd>` (with `/bash <cmd>` as an alias).
|
||||
The Gateway handles commands sent as standalone messages starting with `/`.
|
||||
Host-only bash commands use `! <cmd>` (with `/bash <cmd>` as an alias).
|
||||
|
||||
When a conversation or thread is bound to an ACP session, normal follow-up text routes to that ACP harness. Gateway management commands still stay local: `/acp ...` always reaches the OpenClaw ACP command handler, and `/status` plus `/unfocus` stay local whenever command handling is enabled for the surface.
|
||||
When a conversation is bound to an ACP session, normal text routes to the ACP
|
||||
harness. Gateway management commands remain local: `/acp ...` always reaches
|
||||
the OpenClaw command handler, and `/status` plus `/unfocus` stay local whenever
|
||||
command handling is enabled for the surface.
|
||||
|
||||
There are two related systems:
|
||||
## Three command types
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Commands" icon="terminal">
|
||||
Standalone `/...` messages handled by the Gateway. Must be sent as the
|
||||
only content in the message.
|
||||
</Card>
|
||||
<Card title="Directives" icon="sliders">
|
||||
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`,
|
||||
`/exec`, `/model`, `/queue` — stripped from the message before the model
|
||||
sees it. Persist session settings when sent alone; act as inline hints
|
||||
when sent with other text.
|
||||
</Card>
|
||||
<Card title="Inline shortcuts" icon="bolt">
|
||||
`/help`, `/commands`, `/status`, `/whoami` — run immediately and are
|
||||
stripped before the model sees the remaining text. Authorized senders only.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Commands">
|
||||
Standalone `/...` messages.
|
||||
</Accordion>
|
||||
<Accordion title="Directives">
|
||||
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
|
||||
<Accordion title="Directive behavior details">
|
||||
- Directives are stripped from the message before the model sees it.
|
||||
- In normal chat messages (not directive-only), they are treated as "inline hints" and do **not** persist session settings.
|
||||
- In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
|
||||
- Directives are only applied for **authorized senders**. If `commands.allowFrom` is set, it is the only allowlist used; otherwise authorization comes from channel allowlists/pairing plus `commands.useAccessGroups`. Unauthorized senders see directives treated as plain text.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Inline shortcuts">
|
||||
Allowlisted/authorized senders only: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
|
||||
They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
|
||||
|
||||
- In **directive-only** messages (the message is only directives), they
|
||||
persist to the session and reply with an acknowledgement.
|
||||
- In **normal chat** messages with other text, they act as inline hints and
|
||||
do **not** persist session settings.
|
||||
- Directives only apply for **authorized senders**. If `commands.allowFrom`
|
||||
is set, it is the only allowlist used; otherwise authorization comes from
|
||||
channel allowlists/pairing plus `commands.useAccessGroups`. Unauthorized
|
||||
senders see directives treated as plain text.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Config
|
||||
## Configuration
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -62,329 +77,299 @@ There are two related systems:
|
||||
```
|
||||
|
||||
<ParamField path="commands.text" type="boolean" default="true">
|
||||
Enables parsing `/...` in chat messages. On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), text commands still work even if you set this to `false`.
|
||||
Enables parsing `/...` in chat messages. On surfaces without native commands
|
||||
(WhatsApp, WebChat, Signal, iMessage, Google Chat, Microsoft Teams), text
|
||||
commands work even when set to `false`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
|
||||
Registers native commands. Auto: on for Discord/Telegram; off for Slack (until you add slash commands); ignored for providers without native support. Set `channels.discord.commands.native`, `channels.telegram.commands.native`, or `channels.slack.commands.native` to override per provider (bool or `"auto"`). On Discord, `false` skips slash-command registration and cleanup during startup; previously registered commands may remain visible until you remove them from the Discord app. Slack commands are managed in the Slack app and are not removed automatically.
|
||||
Registers native commands. Auto: on for Discord/Telegram; off for Slack;
|
||||
ignored for providers without native support. Override per-channel with
|
||||
`channels.<provider>.commands.native`. On Discord, `false` skips slash-command
|
||||
registration; previously registered commands may stay visible until removed.
|
||||
</ParamField>
|
||||
On Discord, native command specs may include `descriptionLocalizations`, which OpenClaw publishes as Discord `description_localizations` and includes in reconcile comparisons.
|
||||
|
||||
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
|
||||
Registers **skill** commands natively when supported. Auto: on for Discord/Telegram; off for Slack (Slack requires creating a slash command per skill). Set `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, or `channels.slack.commands.nativeSkills` to override per provider (bool or `"auto"`).
|
||||
Registers skill commands natively when supported. Auto: on for
|
||||
Discord/Telegram; off for Slack. Override with
|
||||
`channels.<provider>.commands.nativeSkills`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.bash" type="boolean" default="false">
|
||||
Enables `! <cmd>` to run host shell commands (`/bash <cmd>` is an alias; requires `tools.elevated` allowlists).
|
||||
Enables `! <cmd>` to run host shell commands (`/bash <cmd>` alias). Requires
|
||||
`tools.elevated` allowlists.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
|
||||
Controls how long bash waits before switching to background mode (`0` backgrounds immediately).
|
||||
How long bash waits before switching to background mode (`0` backgrounds
|
||||
immediately).
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.config" type="boolean" default="false">
|
||||
Enables `/config` (reads/writes `openclaw.json`).
|
||||
Enables `/config` (reads/writes `openclaw.json`). Owner-only.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.mcp" type="boolean" default="false">
|
||||
Enables `/mcp` (reads/writes OpenClaw-managed MCP config under `mcp.servers`).
|
||||
Enables `/mcp` (reads/writes OpenClaw-managed MCP config under `mcp.servers`). Owner-only.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.plugins" type="boolean" default="false">
|
||||
Enables `/plugins` (plugin discovery/status plus install + enable/disable controls).
|
||||
Enables `/plugins` (plugin discovery/status plus install + enable/disable). Owner-only for writes.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.debug" type="boolean" default="false">
|
||||
Enables `/debug` (runtime-only overrides).
|
||||
Enables `/debug` (runtime-only config overrides). Owner-only.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.restart" type="boolean" default="true">
|
||||
Enables `/restart` plus gateway restart tool actions.
|
||||
Enables `/restart` and gateway restart tool actions.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.ownerAllowFrom" type="string[]">
|
||||
Sets the explicit owner allowlist for owner-only command surfaces and owner-gated channel actions. This is the human operator account that can approve dangerous actions and run commands such as `/diagnostics`, `/export-trajectory`, and `/config`. It is separate from `commands.allowFrom` and from DM pairing access.
|
||||
Explicit owner allowlist for owner-only command surfaces. Separate from
|
||||
`commands.allowFrom` and DM pairing access.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
|
||||
Per-channel: makes owner-only commands require **owner identity** to run on that surface. When `true`, the sender must either match a resolved owner candidate (for example an entry in `commands.ownerAllowFrom` or provider-native owner metadata) or hold internal `operator.admin` scope on an internal message channel. A wildcard entry in channel `allowFrom`, or an empty/unresolved owner-candidate list, is **not** sufficient — owner-only commands fail closed on that channel. Leave this off if you want owner-only commands gated only by `ownerAllowFrom` and the standard command allowlists.
|
||||
Per-channel: requires owner identity for owner-only commands. When `true`,
|
||||
sender must match `commands.ownerAllowFrom` or hold internal `operator.admin`
|
||||
scope. A wildcard `allowFrom` entry is **not** sufficient.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
|
||||
Controls how owner ids appear in the system prompt.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.ownerDisplaySecret" type="string">
|
||||
Optionally sets the HMAC secret used when `commands.ownerDisplay="hash"`.
|
||||
HMAC secret used when `commands.ownerDisplay: "hash"`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.allowFrom" type="object">
|
||||
Per-provider allowlist for command authorization. When configured, it is the only authorization source for commands and directives (channel allowlists/pairing and `commands.useAccessGroups` are ignored). Use `"*"` for a global default; provider-specific keys override it.
|
||||
Per-provider allowlist for command authorization. When configured, it is the
|
||||
**only** authorization source for commands and directives. Use `"*"` for a
|
||||
global default; provider-specific keys override it.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
|
||||
Enforces allowlists/policies for commands when `commands.allowFrom` is not set.
|
||||
</ParamField>
|
||||
|
||||
## Command list
|
||||
|
||||
Current source-of-truth:
|
||||
Commands come from three sources:
|
||||
|
||||
- core built-ins come from `src/auto-reply/commands-registry.shared.ts`
|
||||
- generated dock commands come from `src/auto-reply/commands-registry.data.ts`
|
||||
- plugin commands come from plugin `registerCommand()` calls
|
||||
- actual availability on your gateway still depends on config flags, channel surface, and installed/enabled plugins
|
||||
- **Core built-ins:** `src/auto-reply/commands-registry.shared.ts`
|
||||
- **Generated dock commands:** `src/auto-reply/commands-registry.data.ts`
|
||||
- **Plugin commands:** plugin `registerCommand()` calls
|
||||
|
||||
### Core built-in commands
|
||||
Availability depends on config flags, channel surface, and installed/enabled
|
||||
plugins.
|
||||
|
||||
### Core commands
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sessions and runs">
|
||||
- `/new [model]` archives the current session and starts a fresh one; `/reset` wipes the current session in place. They are not aliases.
|
||||
- Control UI intercepts typed `/new` to create and switch to a fresh dashboard session, except when `session.dmScope: "main"` is configured and the current parent is the agent's main session; in that case `/new` resets the main session in place. Typed `/reset` still runs the Gateway's in-place reset.
|
||||
- `/reset soft [message]` keeps the current transcript, drops reused CLI backend session ids, and reruns startup/system-prompt loading in-place.
|
||||
- `/compact [instructions]` compacts the session context. See [Compaction](/concepts/compaction).
|
||||
- `/stop` aborts the current run.
|
||||
- `/session idle <duration|off>` and `/session max-age <duration|off>` manage thread-binding expiry.
|
||||
- `/export-session [path]` exports the current session to HTML. Alias: `/export`.
|
||||
- `/export-trajectory [path]` asks for exec approval, then exports a JSONL [trajectory bundle](/tools/trajectory) for the current session. Use it when you need the prompt, tool, and transcript timeline for one OpenClaw session. In group chats, the approval prompt and export result go to the owner privately. Alias: `/trajectory`.
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/new [model]` | Archive the current session and start a fresh one |
|
||||
| `/reset [soft [message]]` | Reset the current session in place. `soft` keeps the transcript, drops reused CLI backend session ids, and reruns startup |
|
||||
| `/compact [instructions]` | Compact the session context. See [Compaction](/concepts/compaction) |
|
||||
| `/stop` | Abort the current run |
|
||||
| `/session idle <duration\|off>` | Manage thread-binding idle expiry |
|
||||
| `/session max-age <duration\|off>` | Manage thread-binding max-age expiry |
|
||||
| `/export-session [path]` | Export the current session to HTML. Alias: `/export` |
|
||||
| `/export-trajectory [path]` | Export a JSONL trajectory bundle for the current session. Alias: `/trajectory` |
|
||||
|
||||
<Note>
|
||||
Control UI intercepts typed `/new` to create and switch to a fresh
|
||||
dashboard session, except when `session.dmScope: "main"` is configured
|
||||
and the current parent is the agent's main session — in that case `/new`
|
||||
resets the main session in place. Typed `/reset` still runs the Gateway's
|
||||
in-place reset.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Model and run controls">
|
||||
- `/think <level|default>` sets the thinking level or clears the session override. Options come from the active model's provider profile; common levels are `off`, `minimal`, `low`, `medium`, and `high`, with custom levels such as `xhigh`, `adaptive`, `max`, or binary `on` only where supported. Aliases: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` toggles verbose output. Authorized external channel senders may persist the session override; internal gateway/webchat clients need `operator.admin`. Alias: `/v`.
|
||||
- `/trace on|off` toggles plugin trace output for the current session.
|
||||
- `/fast [status|on|off|default]` shows, sets, or clears fast mode.
|
||||
- `/reasoning [on|off|stream]` toggles reasoning visibility. Alias: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` toggles elevated mode. Alias: `/elev`.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` shows or sets exec defaults.
|
||||
- `/model [name|#|status]` shows or sets the model.
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lists configured/auth-available providers or models for a provider; add `all` to browse that provider's full catalog. `provider/*` entries in `agents.defaults.models` make `/model` and `/models` show discovered models only for those providers.
|
||||
- `/queue <mode>` manages active-run queue behavior (`steer`, `followup`, `collect`, `interrupt`) plus options like `debounce:0.5s cap:25 drop:summarize`; `/queue default` or `/queue reset` clears the session override. Mid-run prompts steer by default without a queue directive. See [Command queue](/concepts/queue) and [Steering queue](/concepts/queue-steering).
|
||||
- `/steer <message>` injects guidance into the active run for the current session, independent of `/queue` mode. If steering is unavailable or the session is idle, `<message>` continues as a normal prompt. Alias: `/tell`. See [Steer](/tools/steer).
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/think <level\|default>` | Set the thinking level or clear the session override. Aliases: `/thinking`, `/t` |
|
||||
| `/verbose on\|off\|full` | Toggle verbose output. Alias: `/v` |
|
||||
| `/trace on\|off` | Toggle plugin trace output for the current session |
|
||||
| `/fast [status\|on\|off\|default]` | Show, set, or clear fast mode |
|
||||
| `/reasoning [on\|off\|stream]` | Toggle reasoning visibility. Alias: `/reason` |
|
||||
| `/elevated [on\|off\|ask\|full]` | Toggle elevated mode. Alias: `/elev` |
|
||||
| `/exec host=<auto\|sandbox\|gateway\|node> security=<deny\|allowlist\|full> ask=<off\|on-miss\|always> node=<id>` | Show or set exec defaults |
|
||||
| `/model [name\|#\|status]` | Show or set the model |
|
||||
| `/models [provider] [page] [limit=<n>\|all]` | List configured/auth-available providers or models |
|
||||
| `/queue <mode>` | Manage active-run queue behavior. See [Queue](/concepts/queue) and [Queue steering](/concepts/queue-steering) |
|
||||
| `/steer <message>` | Inject guidance into the active run. Alias: `/tell`. See [Steer](/tools/steer) |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="verbose / trace / fast / reasoning safety">
|
||||
- `/verbose` is for debugging — keep it **off** in normal use.
|
||||
- `/trace` reveals only plugin-owned trace/debug lines; normal verbose chatter stays off.
|
||||
- `/fast on|off` persists a session override; use the Sessions UI `inherit` option to clear it.
|
||||
- `/fast` is provider-specific: OpenAI/Codex map it to `service_tier=priority`; direct Anthropic requests map it to `service_tier=auto` or `standard_only`.
|
||||
- `/reasoning`, `/verbose`, and `/trace` are risky in group settings — they may reveal internal reasoning or plugin diagnostics. Keep them off in group chats.
|
||||
</Accordion>
|
||||
<Accordion title="Model switching details">
|
||||
- `/model` persists the new model immediately to the session.
|
||||
- If the agent is idle, the next run uses it right away.
|
||||
- If a run is active, the switch is marked pending and applied at the next clean retry point.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Discovery and status">
|
||||
- `/help` shows the short help summary.
|
||||
- `/commands` shows the generated command catalog.
|
||||
- `/tools [compact|verbose]` shows what the current agent can use right now.
|
||||
- `/status` shows execution/runtime status, Gateway and system uptime, plus provider usage/quota when available.
|
||||
- `/goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear` manages the current session's durable [goal](/tools/goal).
|
||||
- `/diagnostics [note]` is the owner-only support-report flow for Gateway bugs and Codex harness runs. It asks for explicit exec approval every time before running `openclaw gateway diagnostics export --json`; do not approve diagnostics with an allow-all rule. After approval, it sends a pasteable report with the local bundle path, manifest summary, privacy notes, and relevant session ids. In group chats, the approval prompt and report go to the owner privately. When the active session uses the OpenAI Codex harness, the same approval also sends relevant Codex feedback to OpenAI servers and the completed reply lists the OpenClaw session ids, Codex thread ids, and `codex resume <thread-id>` commands. See [Diagnostics Export](/gateway/diagnostics).
|
||||
- `/crestodian <request>` runs the Crestodian setup and repair helper from an owner DM.
|
||||
- `/tasks` lists active/recent background tasks for the current session.
|
||||
- `/context [list|detail|map|json]` explains how context is assembled. `map` sends a treemap image of the current session context.
|
||||
- `/whoami` shows your sender id. Alias: `/id`.
|
||||
- `/usage off|tokens|full|cost` controls the per-response usage footer or prints a local cost summary.
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/help` | Show the short help summary |
|
||||
| `/commands` | Show the generated command catalog |
|
||||
| `/tools [compact\|verbose]` | Show what the current agent can use right now |
|
||||
| `/status` | Show execution/runtime status, Gateway and system uptime, plus provider usage/quota |
|
||||
| `/goal [status\|start\|pause\|resume\|complete\|block\|clear] ...` | Manage the current session's durable [goal](/tools/goal) |
|
||||
| `/diagnostics [note]` | Owner-only support-report flow. Asks for exec approval every time |
|
||||
| `/crestodian <request>` | Run the Crestodian setup and repair helper from an owner DM |
|
||||
| `/tasks` | List active/recent background tasks for the current session |
|
||||
| `/context [list\|detail\|map\|json]` | Explain how context is assembled |
|
||||
| `/whoami` | Show your sender id. Alias: `/id` |
|
||||
| `/usage off\|tokens\|full\|cost` | Control the per-response usage footer or print a local cost summary |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Skills, allowlists, approvals">
|
||||
- `/skill <name> [input]` runs a skill by name.
|
||||
- `/allowlist [list|add|remove] ...` manages allowlist entries. Text-only.
|
||||
- `/approve <id> <decision>` resolves exec or plugin approval prompts.
|
||||
- `/btw <question>` asks a side question without changing future session context. Alias: `/side`. See [BTW](/tools/btw).
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/skill <name> [input]` | Run a skill by name |
|
||||
| `/allowlist [list\|add\|remove] ...` | Manage allowlist entries. Text-only |
|
||||
| `/approve <id> <decision>` | Resolve exec or plugin approval prompts |
|
||||
| `/btw <question>` | Ask a side question without changing session context. Alias: `/side`. See [BTW](/tools/btw) |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subagents and ACP">
|
||||
- `/subagents list|log|info` inspects sub-agent runs for the current session.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` manages ACP sessions and runtime options.
|
||||
- `/focus <target>` binds the current Discord thread or Telegram topic/conversation to a session target.
|
||||
- `/unfocus` removes the current binding.
|
||||
- `/agents` lists thread-bound agents for the current session.
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/subagents list\|log\|info` | Inspect sub-agent runs for the current session |
|
||||
| `/acp spawn\|cancel\|steer\|close\|sessions\|status\|set-mode\|set\|cwd\|permissions\|timeout\|model\|reset-options\|doctor\|install\|help` | Manage ACP sessions and runtime options |
|
||||
| `/focus <target>` | Bind the current Discord thread or Telegram topic to a session target |
|
||||
| `/unfocus` | Remove the current thread binding |
|
||||
| `/agents` | List thread-bound agents for the current session |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Owner-only writes and admin">
|
||||
- `/config show|get|set|unset` reads or writes `openclaw.json`. Owner-only. Requires `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` reads or writes OpenClaw-managed MCP server config under `mcp.servers`. Owner-only. Requires `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` inspects or mutates plugin state. `/plugin` is an alias. Owner-only for writes. Requires `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` manages runtime-only config overrides. Owner-only. Requires `commands.debug: true`.
|
||||
- `/restart` restarts OpenClaw when enabled. Default: enabled; set `commands.restart: false` to disable it.
|
||||
- `/send on|off|inherit` sets send policy. Owner-only.
|
||||
|
||||
| Command | Requires | Description |
|
||||
| --- | --- | --- |
|
||||
| `/config show\|get\|set\|unset` | `commands.config: true` | Read or write `openclaw.json`. Owner-only |
|
||||
| `/mcp show\|get\|set\|unset` | `commands.mcp: true` | Read or write OpenClaw-managed MCP server config. Owner-only |
|
||||
| `/plugins list\|inspect\|show\|get\|install\|enable\|disable` | `commands.plugins: true` | Inspect or mutate plugin state. Owner-only for writes. Alias: `/plugin` |
|
||||
| `/debug show\|set\|unset\|reset` | `commands.debug: true` | Runtime-only config overrides. Owner-only |
|
||||
| `/restart` | `commands.restart: true` (default) | Restart OpenClaw |
|
||||
| `/send on\|off\|inherit` | owner | Set send policy |
|
||||
</Accordion>
|
||||
<Accordion title="Voice, TTS, channel control">
|
||||
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` controls TTS. See [TTS](/tools/tts).
|
||||
- `/activation mention|always` sets group activation mode.
|
||||
- `/bash <command>` runs a host shell command. Text-only. Alias: `! <command>`. Requires `commands.bash: true` plus `tools.elevated` allowlists.
|
||||
- `!poll [sessionId]` checks a background bash job.
|
||||
- `!stop [sessionId]` stops a background bash job.
|
||||
|
||||
<Accordion title="Voice, TTS, channel control">
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/tts on\|off\|status\|chat\|latest\|provider\|limit\|summary\|audio\|help` | Control TTS. See [TTS](/tools/tts) |
|
||||
| `/activation mention\|always` | Set group activation mode |
|
||||
| `/bash <command>` | Run a host shell command. Alias: `! <command>`. Requires `commands.bash: true` |
|
||||
| `!poll [sessionId]` | Check a background bash job |
|
||||
| `!stop [sessionId]` | Stop a background bash job |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Generated dock commands
|
||||
### Dock commands
|
||||
|
||||
Dock commands switch the current session's reply route to another linked
|
||||
channel. See [Channel docking](/concepts/channel-docking) for setup,
|
||||
examples, and troubleshooting.
|
||||
Dock commands switch the active session's reply route to another linked channel.
|
||||
See [Channel docking](/concepts/channel-docking) for setup and troubleshooting.
|
||||
|
||||
Dock commands are generated from channel plugins with native-command support. Current bundled set:
|
||||
Generated from channel plugins with native-command support:
|
||||
|
||||
- `/dock-discord` (alias: `/dock_discord`)
|
||||
- `/dock-mattermost` (alias: `/dock_mattermost`)
|
||||
- `/dock-slack` (alias: `/dock_slack`)
|
||||
- `/dock-telegram` (alias: `/dock_telegram`)
|
||||
|
||||
Use dock commands from a direct chat to switch the current session's reply route to another linked channel. The agent keeps the same session context, but future replies for that session are delivered to the selected channel peer.
|
||||
|
||||
Dock commands require `session.identityLinks`. The source sender and target peer must be in the same identity group, for example `["telegram:123", "discord:456"]`. If a Telegram user with id `123` sends `/dock_discord`, OpenClaw stores `lastChannel: "discord"` and `lastTo: "456"` on the active session. If the sender is not linked to a Discord peer, the command replies with a setup hint instead of falling through to normal chat.
|
||||
|
||||
Docking changes the active session route only. It does not create channel accounts, grant access, bypass channel allowlists, or move transcript history to another session. Use `/dock-telegram`, `/dock-slack`, `/dock-mattermost`, or another generated dock command to switch the route again.
|
||||
Dock commands require `session.identityLinks`. The source sender and target peer
|
||||
must be in the same identity group.
|
||||
|
||||
### Bundled plugin commands
|
||||
|
||||
Bundled plugins can add more slash commands. Current bundled commands in this repo:
|
||||
| Command | Description |
|
||||
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `/dreaming [on\|off\|status\|help]` | Toggle memory dreaming. See [Dreaming](/concepts/dreaming) |
|
||||
| `/pair [qr\|status\|pending\|approve\|cleanup\|notify]` | Manage device pairing. See [Pairing](/channels/pairing) |
|
||||
| `/phone status\|arm ...\|disarm` | Temporarily arm high-risk phone node commands |
|
||||
| `/voice status\|list\|set <voiceId>` | Manage Talk voice config. Discord native name: `/talkvoice` |
|
||||
| `/card ...` | Send LINE rich card presets. See [LINE](/channels/line) |
|
||||
| `/codex status\|models\|threads\|resume\|compact\|review\|diagnostics\|account\|mcp\|skills` | Control the Codex app-server harness. See [Codex harness](/plugins/codex-harness) |
|
||||
|
||||
- `/dreaming [on|off|status|help]` toggles memory dreaming. See [Dreaming](/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` manages device pairing/setup flow. See [Pairing](/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` temporarily arms high-risk phone node commands.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` manages Talk voice config. On Discord, the native command name is `/talkvoice`.
|
||||
- `/card ...` sends LINE rich card presets. See [LINE](/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspects and controls the bundled Codex app-server harness. See [Codex harness](/plugins/codex-harness).
|
||||
- QQBot-only commands:
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
- `/bot-help`
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
QQBot-only: `/bot-ping`, `/bot-version`, `/bot-help`, `/bot-upgrade`, `/bot-logs`
|
||||
|
||||
### Dynamic skill commands
|
||||
### Skill commands
|
||||
|
||||
User-invocable skills are also exposed as slash commands:
|
||||
User-invocable skills are exposed as slash commands:
|
||||
|
||||
- `/skill <name> [input]` always works as the generic entrypoint.
|
||||
- skills may also appear as direct commands like `/prose` when the skill/plugin registers them.
|
||||
- native skill-command registration is controlled by `commands.nativeSkills` and `channels.<provider>.commands.nativeSkills`.
|
||||
- command specs can provide `descriptionLocalizations` for native surfaces that support localized descriptions, including Discord.
|
||||
- Skills may register as direct commands (e.g. `/prose` for OpenProse).
|
||||
- Native skill-command registration is controlled by `commands.nativeSkills` and
|
||||
`channels.<provider>.commands.nativeSkills`.
|
||||
- Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Argument and parser notes">
|
||||
- Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` accepts a model alias, `provider/model`, or a provider name (fuzzy match); if no match, the text is treated as the message body.
|
||||
- For full provider usage breakdown, use `openclaw status --usage`.
|
||||
- `/allowlist add|remove` requires `commands.config=true` and honors channel `configWrites`.
|
||||
- In multi-account channels, config-targeted `/allowlist --account <id>` and `/config set channels.<provider>.accounts.<id>...` also honor the target account's `configWrites`.
|
||||
- `/usage` controls the per-response usage footer; `/usage cost` prints a local cost summary from OpenClaw session logs.
|
||||
- `/restart` is enabled by default; set `commands.restart: false` to disable it.
|
||||
- `/plugins install <spec>` accepts the same plugin specs as `openclaw plugins install`: local path/archive, npm package, `git:<repo>`, or `clawhub:<pkg>`. Managed Gateways restart automatically because plugin source modules changed.
|
||||
- `/plugins enable|disable` updates plugin config and triggers Gateway plugin reload for new agent turns.
|
||||
<Accordion title="Skill command dispatch">
|
||||
By default, skill commands route to the model as a normal request.
|
||||
|
||||
Skills can declare `command-dispatch: tool` to route directly to a tool
|
||||
(deterministic, no model involvement). Example: `/prose` (OpenProse plugin)
|
||||
— see [OpenProse](/prose).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Channel-specific behavior">
|
||||
- Discord-only native command: `/vc join|leave|status` controls voice channels (not available as text). `join` requires a guild and selected voice/stage channel. Requires `channels.discord.voice` and native commands.
|
||||
- Discord thread-binding commands (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) require effective thread bindings to be enabled (`session.threadBindings.enabled` and/or `channels.discord.threadBindings.enabled`).
|
||||
- ACP command reference and runtime behavior: [ACP agents](/tools/acp-agents).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Verbose / trace / fast / reasoning safety">
|
||||
- `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
|
||||
- `/trace` is narrower than `/verbose`: it only reveals plugin-owned trace/debug lines and keeps normal verbose tool chatter off.
|
||||
- `/fast on|off` persists a session override. Use the Sessions UI `inherit` option to clear it and fall back to config defaults.
|
||||
- `/fast` is provider-specific: OpenAI/OpenAI Codex map it to `service_tier=priority` on native Responses endpoints, while direct public Anthropic requests, including OAuth-authenticated traffic sent to `api.anthropic.com`, map it to `service_tier=auto` or `standard_only`. See [OpenAI](/providers/openai) and [Anthropic](/providers/anthropic).
|
||||
- Tool failure summaries are still shown when relevant, but detailed failure text is only included when `/verbose full` is enabled.
|
||||
- `/reasoning`, `/verbose`, and `/trace` are risky in group settings: they may reveal internal reasoning, tool output, or plugin diagnostics you did not intend to expose. Prefer leaving them off, especially in group chats.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Model switching">
|
||||
- `/model` persists the new session model immediately.
|
||||
- If the agent is idle, the next run uses it right away.
|
||||
- If a run is already active, OpenClaw marks a live switch as pending and only restarts into the new model at a clean retry point.
|
||||
- If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn.
|
||||
- In the local TUI, `/crestodian [request]` returns from the normal agent TUI to Crestodian. This is separate from message-channel rescue mode and does not grant remote config authority.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Fast path and inline shortcuts">
|
||||
- **Fast path:** command-only messages from allowlisted senders are handled immediately (bypass queue + model).
|
||||
- **Group mention gating:** command-only messages from allowlisted senders bypass mention requirements.
|
||||
- **Inline shortcuts (allowlisted senders only):** certain commands also work when embedded in a normal message and are stripped before the model sees the remaining text.
|
||||
- Example: `hey /status` triggers a status reply, and the remaining text continues through the normal flow.
|
||||
- Currently: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
- Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skill commands and native arguments">
|
||||
- **Skill commands:** `user-invocable` skills are exposed as slash commands. Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes (e.g. `_2`).
|
||||
- `/skill <name> [input]` runs a skill by name (useful when native command limits prevent per-skill commands).
|
||||
- By default, skill commands are forwarded to the model as a normal request.
|
||||
- Skills may optionally declare `command-dispatch: tool` to route the command directly to a tool (deterministic, no model).
|
||||
- Example: `/prose` (OpenProse plugin) — see [OpenProse](/prose).
|
||||
- **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg. Dynamic choices are resolved against the target session model, so model-specific options such as `/think` levels follow that session's `/model` override.
|
||||
|
||||
<Accordion title="Native command arguments">
|
||||
Discord uses autocomplete for dynamic options and button menus when required
|
||||
args are omitted. Telegram and Slack show a button menu for commands with
|
||||
choices. Dynamic choices resolve against the target session model, so model-
|
||||
specific options like `/think` levels follow the session's `/model` override.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## `/tools`
|
||||
## `/tools` — what the agent can use now
|
||||
|
||||
`/tools` answers a runtime question, not a config question: **what this agent can use right now in this conversation**.
|
||||
|
||||
- Default `/tools` is compact and optimized for quick scanning.
|
||||
- `/tools verbose` adds short descriptions.
|
||||
- Native-command surfaces that support arguments expose the same mode switch as `compact|verbose`.
|
||||
- Results are session-scoped, so changing agent, channel, thread, sender authorization, or model can change the output.
|
||||
- `/tools` includes tools that are actually reachable at runtime, including core tools, connected plugin tools, and channel-owned tools.
|
||||
|
||||
For profile and override editing, use the Control UI Tools panel or config/catalog surfaces instead of treating `/tools` as a static catalog.
|
||||
|
||||
## Usage surfaces (what shows where)
|
||||
|
||||
- **Provider usage/quota** (example: "Claude 80% left") shows up in `/status` for the current model provider when usage tracking is enabled. OpenClaw normalizes provider windows to `% left`; for MiniMax, remaining-only percent fields are inverted before display, and `model_remains` responses prefer the chat-model entry plus a model-tagged plan label.
|
||||
- **Token/cache lines** in `/status` can fall back to the latest transcript usage entry when the live session snapshot is sparse. Existing nonzero live values still win, and transcript fallback can also recover the active runtime model label plus a larger prompt-oriented total when stored totals are missing or smaller.
|
||||
- **Execution vs runtime:** `/status` reports `Execution` for the effective sandbox path and `Runtime` for who is actually running the session: `OpenClaw Default`, `OpenAI Codex`, a CLI backend, or an ACP backend.
|
||||
- **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies).
|
||||
- `/model status` is about **models/auth/endpoints**, not usage.
|
||||
|
||||
## Model selection (`/model`)
|
||||
|
||||
`/model` is implemented as a directive.
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
/model
|
||||
/model list
|
||||
/model 3
|
||||
/model openai/gpt-5.4
|
||||
/model opus@anthropic:default
|
||||
/model status
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `/model` and `/model list` show a compact, numbered picker (model family + available providers).
|
||||
- On Discord, `/model` and `/models` open an interactive picker with provider and model dropdowns plus a Submit step. The picker respects `agents.defaults.models`, including `provider/*` entries, so provider-scoped discovery can keep the picker below Discord's 25-option component limit.
|
||||
- `/model <#>` selects from that picker (and prefers the current provider when possible).
|
||||
- `/model status` shows the detailed view, including configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
|
||||
|
||||
## Debug overrides
|
||||
|
||||
`/debug` lets you set **runtime-only** config overrides (memory, not disk). Owner-only. Disabled by default; enable with `commands.debug: true`.
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
/debug show
|
||||
/debug set messages.responsePrefix="[openclaw]"
|
||||
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
|
||||
/debug unset messages.responsePrefix
|
||||
/debug reset
|
||||
```
|
||||
|
||||
<Note>
|
||||
Overrides apply immediately to new config reads, but do **not** write to `openclaw.json`. Use `/debug reset` to clear all overrides and return to the on-disk config.
|
||||
</Note>
|
||||
|
||||
## Plugin trace output
|
||||
|
||||
`/trace` lets you toggle **session-scoped plugin trace/debug lines** without turning on full verbose mode.
|
||||
|
||||
Examples:
|
||||
`/tools` answers a runtime question: **what this agent can use right now in this
|
||||
conversation** — not a static config catalog.
|
||||
|
||||
```text
|
||||
/trace
|
||||
/trace on
|
||||
/trace off
|
||||
/tools # compact view
|
||||
/tools verbose # with short descriptions
|
||||
```
|
||||
|
||||
Notes:
|
||||
Results are session-scoped. Changing agent, channel, thread, sender
|
||||
authorization, or model can change the output. For profile and override editing,
|
||||
use the Control UI Tools panel or config surfaces.
|
||||
|
||||
- `/trace` with no argument shows the current session trace state.
|
||||
- `/trace on` enables plugin trace lines for the current session.
|
||||
- `/trace off` disables them again.
|
||||
- Plugin trace lines can appear in `/status` and as a follow-up diagnostic message after the normal assistant reply.
|
||||
- `/trace` does not replace `/debug`; `/debug` still manages runtime-only config overrides.
|
||||
- `/trace` does not replace `/verbose`; normal verbose tool/status output still belongs to `/verbose`.
|
||||
|
||||
## Config updates
|
||||
|
||||
`/config` writes to your on-disk config (`openclaw.json`). Owner-only. Disabled by default; enable with `commands.config: true`.
|
||||
|
||||
Examples:
|
||||
## `/model` — model selection
|
||||
|
||||
```text
|
||||
/model # show model picker
|
||||
/model list # same
|
||||
/model 3 # select by number from picker
|
||||
/model openai/gpt-5.4
|
||||
/model opus@anthropic:default
|
||||
/model status # detailed view with endpoint and API mode
|
||||
```
|
||||
|
||||
On Discord, `/model` and `/models` open an interactive picker with provider and
|
||||
model dropdowns. The picker respects `agents.defaults.models`, including
|
||||
`provider/*` entries.
|
||||
|
||||
## `/config` — on-disk config writes
|
||||
|
||||
<Note>
|
||||
Owner-only. Disabled by default — enable with `commands.config: true`.
|
||||
</Note>
|
||||
|
||||
```text
|
||||
/config show
|
||||
/config show messages.responsePrefix
|
||||
/config get messages.responsePrefix
|
||||
@@ -392,16 +377,15 @@ Examples:
|
||||
/config unset messages.responsePrefix
|
||||
```
|
||||
|
||||
Config is validated before write. Invalid changes are rejected. `/config`
|
||||
updates persist across restarts.
|
||||
|
||||
## `/mcp` — MCP server config
|
||||
|
||||
<Note>
|
||||
Config is validated before write; invalid changes are rejected. `/config` updates persist across restarts.
|
||||
Owner-only. Disabled by default — enable with `commands.mcp: true`.
|
||||
</Note>
|
||||
|
||||
## MCP updates
|
||||
|
||||
`/mcp` writes OpenClaw-managed MCP server definitions under `mcp.servers`. Owner-only. Disabled by default; enable with `commands.mcp: true`.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
/mcp show
|
||||
/mcp show context7
|
||||
@@ -409,15 +393,28 @@ Examples:
|
||||
/mcp unset context7
|
||||
```
|
||||
|
||||
`/mcp` stores config in OpenClaw config, not embedded-agent project settings.
|
||||
|
||||
## `/debug` — runtime-only overrides
|
||||
|
||||
<Note>
|
||||
`/mcp` stores config in OpenClaw config, not embedded-agent project settings. Runtime adapters decide which transports are actually executable.
|
||||
Owner-only. Disabled by default — enable with `commands.debug: true`.
|
||||
Overrides apply immediately to new config reads but do **not** write to disk.
|
||||
</Note>
|
||||
|
||||
## Plugin updates
|
||||
```text
|
||||
/debug show
|
||||
/debug set messages.responsePrefix="[openclaw]"
|
||||
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
|
||||
/debug unset messages.responsePrefix
|
||||
/debug reset
|
||||
```
|
||||
|
||||
`/plugins` lets operators inspect discovered plugins and toggle enablement in config. Read-only flows can use `/plugin` as an alias. Disabled by default; enable with `commands.plugins: true`.
|
||||
## `/plugins` — plugin management
|
||||
|
||||
Examples:
|
||||
<Note>
|
||||
Owner-only for writes. Disabled by default — enable with `commands.plugins: true`.
|
||||
</Note>
|
||||
|
||||
```text
|
||||
/plugins
|
||||
@@ -425,63 +422,92 @@ Examples:
|
||||
/plugin show context7
|
||||
/plugins enable context7
|
||||
/plugins disable context7
|
||||
/plugins install ./path/to/plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
- `/plugins list` and `/plugins show` use real plugin discovery against the current workspace plus on-disk config.
|
||||
- `/plugins install` installs from ClawHub, npm, git, local directories, and archives.
|
||||
- `/plugins enable|disable` updates plugin config only; it does not install or uninstall plugins.
|
||||
- Enable and disable changes hot-reload Gateway plugin runtime surfaces for new agent turns; install restarts managed Gateways automatically because plugin source modules changed.
|
||||
`/plugins enable|disable` updates plugin config and hot-reloads the Gateway
|
||||
plugin runtime for new agent turns. `/plugins install` restarts managed
|
||||
Gateways automatically because plugin source modules changed.
|
||||
|
||||
</Note>
|
||||
## `/trace` — plugin trace output
|
||||
|
||||
## Surface notes
|
||||
```text
|
||||
/trace # show current trace state
|
||||
/trace on
|
||||
/trace off
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sessions per surface">
|
||||
- **Text commands** run in the normal chat session (DMs share `main`, groups have their own session).
|
||||
- **Native commands** use isolated sessions:
|
||||
- Discord: `agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (prefix configurable via `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Telegram: `telegram:slash:<userId>` (targets the chat session via `CommandTargetSessionKey`)
|
||||
- **`/stop`** targets the active chat session so it can abort the current run.
|
||||
`/trace` reveals session-scoped plugin trace/debug lines without full verbose
|
||||
mode. It does not replace `/debug` (runtime overrides) or `/verbose` (normal
|
||||
tool output).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Slack specifics">
|
||||
`channels.slack.slashCommand` is still supported for a single `/openclaw`-style command. If you enable `commands.native`, you must create one Slack slash command per built-in command (same names as `/help`). Command argument menus for Slack are delivered as ephemeral Block Kit buttons.
|
||||
## `/btw` — side questions
|
||||
|
||||
Slack native exception: register `/agentstatus` (not `/status`) because Slack reserves `/status`. Text `/status` still works in Slack messages.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## BTW side questions
|
||||
|
||||
`/btw` is a quick **side question** about the current session. `/side` is an alias.
|
||||
|
||||
Unlike normal chat:
|
||||
|
||||
- it uses the current session as background context,
|
||||
- in Codex harness sessions, it runs as an ephemeral Codex side thread with the
|
||||
current Codex permissions and native tool surface,
|
||||
- in non-Codex sessions, it keeps the older direct one-shot side-call behavior,
|
||||
- it does not change future session context,
|
||||
- it is not written to transcript history,
|
||||
- it is delivered as a live side result instead of a normal assistant message.
|
||||
|
||||
That makes `/btw` useful when you want a temporary clarification while the main task keeps going.
|
||||
|
||||
Example:
|
||||
`/btw` is a quick side question about the current session context. Alias: `/side`.
|
||||
|
||||
```text
|
||||
/btw what are we doing right now?
|
||||
/side what changed while the main run continued?
|
||||
```
|
||||
|
||||
See [BTW Side Questions](/tools/btw) for the full behavior and client UX details.
|
||||
Unlike a normal message:
|
||||
|
||||
- Uses the current session as background context.
|
||||
- In Codex harness sessions, runs as an ephemeral Codex side thread.
|
||||
- Does **not** change future session context.
|
||||
- Is not written to transcript history.
|
||||
|
||||
See [BTW side questions](/tools/btw) for the full behavior.
|
||||
|
||||
## Surface notes
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Session scoping per surface">
|
||||
- **Text commands:** run in the normal chat session (DMs share `main`, groups have their own session).
|
||||
- **Native Discord commands:** `agent:<agentId>:discord:slash:<userId>`
|
||||
- **Native Slack commands:** `agent:<agentId>:slack:slash:<userId>` (prefix configurable via `channels.slack.slashCommand.sessionPrefix`)
|
||||
- **Native Telegram commands:** `telegram:slash:<userId>` (targets the chat session via `CommandTargetSessionKey`)
|
||||
- **`/stop`** targets the active chat session to abort the current run.
|
||||
</Accordion>
|
||||
<Accordion title="Slack specifics">
|
||||
`channels.slack.slashCommand` supports a single `/openclaw`-style command.
|
||||
With `commands.native: true`, create one Slack slash command per built-in
|
||||
command. Register `/agentstatus` (not `/status`) because Slack reserves
|
||||
`/status`. Text `/status` still works in Slack messages.
|
||||
</Accordion>
|
||||
<Accordion title="Fast path and inline shortcuts">
|
||||
- Command-only messages from allowlisted senders are handled immediately (bypass queue + model).
|
||||
- Inline shortcuts (`/help`, `/commands`, `/status`, `/whoami`) also work embedded in normal messages and are stripped before the model sees the remaining text.
|
||||
- Unauthorized command-only messages are silently ignored; inline `/...` tokens are treated as plain text.
|
||||
</Accordion>
|
||||
<Accordion title="Argument notes">
|
||||
- Commands accept an optional `:` between the command and args (`/think: high`, `/send: on`).
|
||||
- `/new <model>` accepts a model alias, `provider/model`, or a provider name (fuzzy match); if no match, the text is treated as the message body.
|
||||
- `/allowlist add|remove` requires `commands.config: true` and honors channel `configWrites`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Provider usage and status
|
||||
|
||||
- **Provider usage/quota** (e.g., "Claude 80% left") shows in `/status` for the current model provider when usage tracking is enabled.
|
||||
- **Token/cache lines** in `/status` can fall back to the latest transcript usage entry when the live session snapshot is sparse.
|
||||
- **Execution vs runtime:** `/status` reports `Execution` for the effective sandbox path and `Runtime` for who is running the session: `OpenClaw Default`, `OpenAI Codex`, a CLI backend, or an ACP backend.
|
||||
- **Per-response tokens/cost:** controlled by `/usage off|tokens|full`.
|
||||
- `/model status` is about models/auth/endpoints, not usage.
|
||||
|
||||
## Related
|
||||
|
||||
- [Creating skills](/tools/creating-skills)
|
||||
- [Skills](/tools/skills)
|
||||
- [Skills config](/tools/skills-config)
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Skills" href="/tools/skills" icon="puzzle-piece">
|
||||
How skill slash commands are registered and gated.
|
||||
</Card>
|
||||
<Card title="Creating skills" href="/tools/creating-skills" icon="hammer">
|
||||
Build a skill that registers its own slash command.
|
||||
</Card>
|
||||
<Card title="BTW" href="/tools/btw" icon="comments">
|
||||
Side questions without changing session context.
|
||||
</Card>
|
||||
<Card title="Steer" href="/tools/steer" icon="compass">
|
||||
Guide the agent mid-run with `/steer`.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Reference in New Issue
Block a user