Convert OpenClaw skills into properly configured agents with correct workspace setup, binding, and orchestration. Solves common agent creation failures (thre...
Transform any OpenClaw skill into a fully functional agent with proper workspace configuration and session management. Solves common failures like thread=true is unavailable and mode="session" requires thread=true.
~/.openclaw/agents/agents.list configurationgateway tool with config.patch actioncwd to agent workspace directoryFor detailed guidance, refer to:
scripts/skill_to_agent.js - Main conversion script| Scenario | Mode | Thread | Best For |
|---|---|---|---|
| Discord/Telegram | session | true | Group discussions |
| WebChat/Control UI | run | false | One-shot tasks |
| Isolated Processing | session | false | Background work |
| Cron/Scheduled | run | false | Automated tasks |
Decision Tree:
thread=true, mode=sessionthread=false, mode=sessionthread=false, mode=runError 1: thread=true is unavailable
mode="run" without thread bindingError 2: mode="session" requires thread=true
mode="session", thread=false, runtime="subagent"Error 3: Agent lacks tool access
Error 4: Workspace files not accessible
cwd parameter when spawning agentcwdError 5: Agent can't find its identity files
cwd to agent workspace directoryread commandsError 6: Agent not recognized by OpenClaw system
agents.list configurationgateway tool with config.patch actionWhen spawning an agent, ALWAYS set the cwd parameter to the agent's workspace directory:
sessions_spawn({
task: "Agent instructions...",
label: "agent-name",
runtime: "subagent",
mode: "session", // or "run"
cwd: "/Users/nimbletenthousand/.openclaw/agents/agent-name",
timeoutSeconds: 300
});
Without cwd, the agent cannot find its identity files (IDENTITY.md, SOUL.md, etc.) and will fail to function properly.
After creating an agent workspace, register it in OpenClaw's configuration:
gateway({
action: "config.patch",
raw: JSON.stringify({
agents: {
list: [
{
id: "agent-name",
name: "Agent Display Name",
workspace: "/Users/nimbletenthousand/.openclaw/workspace",
agentDir: "/Users/nimbletenthousand/.openclaw/agents/agent-name"
}
]
}
}),
note: "Added [agent-name] to agents configuration"
});
The gateway will restart automatically to apply the configuration. Without registration, the agent won't be recognized as a configured agent in the system.
# Check skill structure
node scripts/skill_to_agent.js --analyze --skill /path/to/skill
# Create agent workspace
node scripts/skill_to_agent.js --create --skill /path/to/skill --agent agent-name
# Spawn agent with correct binding
node scripts/skill_to_agent.js --spawn --agent agent-name --mode session --cwd /path/to/agent-workspace
sessions_list regularlyAfter creating an agent:
sessions_listFor advanced usage and complete examples, see the reference files.
ZIP package — ready to use