OpenServ
OpenClaw

OpenClaw Quickstart

Quickstart guide for building with OpenClaw using OpenServ skills.

Using OpenServ Skills with OpenClaw

OpenClaw is designed to be the "IDE for Autonomous Agents". It runs directly on your machine (or VPS), meaning it has full access to your filesystem and tools.

Learn about OpenServ skills and OpenClaw basics — how skills work, how OpenClaw loads them, and how to start building autonomous agents.

Phase 1: Loading Skills (Just Talk to It)

OpenClaw is an autonomous agent. It has access to its own terminal and filesystem. You don't need to type commands manually—just tell OpenClaw what to do.

Option A: Install All OpenServ Skills (ClawHub)

ClawHub is the public skill registry for OpenClaw — like an App Store for agent skills. Skills are installed into your ./skills folder and OpenClaw picks them up in the next session.

Copy & Paste:

Please force install all of these skills from ClawHub for me:
clawhub install openserv-client
clawhub install openserv-agent-sdk
clawhub install openserv-multi-agent-workflows
clawhub install openserv-launch
clawhub install openserv-ideaboard-api

What happens:

  1. OpenClaw runs each clawhub install command in its terminal.
  2. Each skill (SKILL.md, reference.md, troubleshooting.md, examples) is downloaded into ./skills/.
  3. OpenClaw now knows how to build agents, workflows, multi-agent pipelines, token launches, and Ideaboard services.

Option B: "Clone the Repo" (Git)

If you see a GitHub repo you want to use, just paste the link.

Copy & Paste:

Clone https://github.com/openserv-labs/skills.git into a local folder so you can read the docs.

What happens:

  1. OpenClaw accesses its terminal.
  2. It runs git clone ....
  3. It reads the files and now knows how to use them.

Option C: "Read this URL"

Copy & Paste:

Read https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md and tell me how `provision()` works.

Phase 2: Project Setup & Authentication

Before building anything, you need a project folder and a wallet. OpenClaw will set both up for you — just pick your path.

⚠️ OpenClaw is still in early stages of development. We strongly recommend starting with a fresh wallet and only funding it with what you're comfortable using. Do not use your main wallet.

Option A: Fresh Start (Fastest)

No wallet? No problem. OpenClaw will create everything from scratch.

Copy & Paste:

Create a new folder called "openserv-agents" in the workspace. Inside it, initialize a new Node.js project with TypeScript. Then run provision() to generate a brand-new wallet and save the private key to the .env file in that folder. Show me the wallet address when done.

What happens:

  1. OpenClaw creates the openserv-agents/ folder and runs npm init.
  2. It writes code that calls provision().
  3. provision() generates a fresh wallet, saves WALLET_PRIVATE_KEY to .env, and registers you on the platform.
  4. All your agents in Phase 3 will use this same folder and wallet.

Option B: Bring Your Own Key (BYOK)

Already have a wallet you want to use? Two ways to provide it:

Way 1 — Paste it in chat (simplest):

Create a new folder called "openserv-agents" in the workspace. Inside it, initialize a Node.js project with TypeScript. Then create a .env file with WALLET_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE and run provision() to register. Show me the wallet address when done.

Way 2 — Already have it in your shell environment:

Create a new folder called "openserv-agents" in the workspace. Inside it, initialize a Node.js project with TypeScript. Then create a .env file and write my WALLET_PRIVATE_KEY from the shell environment into it. Run provision() to register and show me the wallet address.

Bonus: "Where's my private key?"

If you have a wallet but don't know how to access the key:

Show me the shell command to export my wallet private key so I can use it for OpenServ authentication.

Adding API Keys Later

If your agents need external API keys (e.g., Twitter, Slack), just add them to the .env in your project folder:

WALLET_PRIVATE_KEY=0x...  # already set by provision()
TWITTER_API_KEY=your-key-here
SLACK_WEBHOOK_URL=https://hooks.slack.com/...

In your agent code: const key = process.env.TWITTER_API_KEY. That's it — dotenv picks them up at runtime.

Debugging Auth

If provision() fails:

  1. Check the console output — provision() logs your wallet address on first run.
  2. Make sure the wallet has enough ETH on the correct network (e.g., Base) for gas.
  3. If balance is 0, send some ETH to the address logged in step 1.
  4. Re-run your agent.

Phase 3: Build & Go Wild

Now that OpenClaw has the skills (manuals) and the keys (auth), you can just build. Each prompt below is split into two parts: customize the top, leave the bottom alone.

The Master Prompt (Standard)

Use this for most agents.

Copy & Paste:

--- 📋 BUILD REQUEST (customize to whatever you need) ---

Build a simple agent that [DESCRIBE WHAT YOU WANT — e.g., "generates haiku poems about any topic"]. Create a workflow with a webhook trigger, trigger it once, and show me the response.

--- 🤖 OPENSERV GUARDRAILS (standard — don't change) ---

Read ALL of these skills before writing any code:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-agent-sdk: https://github.com/openserv-labs/skills/blob/main/skills/openserv-agent-sdk/SKILL.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md

CONCEPT → CODE:

Auth: provision() creates/reuses wallet, writes WALLET_PRIVATE_KEY to .env on first run. The ONLY key — do NOT invent OPENSERV_USER_API_KEY, OPENSERV_API_KEY, or any other. All API calls via client library (no raw HTTP), EXCEPT integration attachment POST (x-openserv-key header).

Triggers: webhook → triggers.webhook({ waitForCompletion: true, timeout: 600 }); cron → triggers.cron(schedule); x402 → triggers.x402. Always activate after creation.
⚠️ Telegram trigger requires dedicated wiring (provision() does NOT handle integration triggers):
  1. Create trigger: client.triggers.create({ workflowId, name, integrationConnectionId, trigger_name: 'on-message', props: { regexMatch: '.*' } }) + activate
  2. Create task: client.tasks.create({ workflowId, agentId, description })
  3. Attach integration to task via REST: POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId } — use header x-openserv-key: userApiKey (the string returned by client.authenticate(WALLET_PRIVATE_KEY), NOT Bearer)
  4. Wire trigger→task graph: client.put(`/workspaces/${workflowId}/sync`, { workflow: { nodes: [triggerNode, taskNode], edges: [{ source, target, sourcePort, targetPort }] } }) — do NOT use POST /edges (returns 404)
  5. Set running: client.workflows.setRunning({ id: workflowId })

Integrations: User adds in UI first (Connect → Integrations). Discover: listConnections() or getOrCreateConnection('name'). Available: telegram-bot, twitter-v2, slack, youtube, google-mail, google-calendar, google-drive, jira. Attach to task (required, declarative does NOT work): POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId: id }. If missing, STOP and tell user to add in UI.

Agents: Marketplace → client.agents.listMarketplace(), assign by id. Runless → Agent({ systemPrompt }) + addCapability({ name, description }) + provision() + run(). Runnable → same + inputSchema + run function. Custom agents must be running before triggering.

Workflows: Goal must be DETAILED (not "test"). Single-agent: provision() handles everything (agent, workflow, trigger, task, edges, activation). Multi-agent: client.workflows.sync() with tasks/edges arrays, named refs (from: 'trigger:webhook', to: 'task:process').

Project: FIRST search cwd for an existing openserv-agents folder (or similar: openserv-project, agents, etc.) and check for .env with WALLET_PRIVATE_KEY. If found → use that folder and its .env, create your script inside it. ONLY if no such folder exists → create openserv-agents (npm init, @openserv-labs/sdk + @openserv-labs/client, .env with WALLET_PRIVATE_KEY). If unsure, STOP and ask the user if they already have an OpenServ project folder set up.

Execute: RUN with `npx tsx <file>.ts` — don't just write it. Print workflowId, triggerId, taskId(s). Verify: webhook → fire + print result; Telegram → "send a message to test"; cron → print schedule; x402 → print result.paywallUrl.

The "Builder" Prompt (Custom Logic)

Use this when you need the agent to execute code (fetching APIs, database calls, etc.).

Copy & Paste:

--- 📋 BUILD REQUEST (customize to whatever you need) ---

Build a custom agent with a capability called "[NAME]" that takes [ARGS] and [DESCRIBE LOGIC — e.g., "fetches weather from open-meteo.com and returns a forecast"]. Create a workflow with a webhook trigger, trigger it once with "[TEST_INPUT]", and show me the response.

--- 🤖 OPENSERV GUARDRAILS (standard — don't change) ---

Read ALL of these skills before writing any code:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-agent-sdk: https://github.com/openserv-labs/skills/blob/main/skills/openserv-agent-sdk/SKILL.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md

CONCEPT → CODE:

Auth: provision() creates/reuses wallet, writes WALLET_PRIVATE_KEY to .env on first run. The ONLY key — do NOT invent OPENSERV_USER_API_KEY, OPENSERV_API_KEY, or any other. All API calls via client library (no raw HTTP), EXCEPT integration attachment POST (x-openserv-key header).

Triggers: webhook → triggers.webhook({ waitForCompletion: true, timeout: 600 }); cron → triggers.cron(schedule); x402 → triggers.x402. Always activate after creation.
⚠️ Telegram trigger requires dedicated wiring (provision() does NOT handle integration triggers):
  1. Create trigger: client.triggers.create({ workflowId, name, integrationConnectionId, trigger_name: 'on-message', props: { regexMatch: '.*' } }) + activate
  2. Create task: client.tasks.create({ workflowId, agentId, description })
  3. Attach integration to task via REST: POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId } — use header x-openserv-key: userApiKey (the string returned by client.authenticate(WALLET_PRIVATE_KEY), NOT Bearer)
  4. Wire trigger→task graph: client.put(`/workspaces/${workflowId}/sync`, { workflow: { nodes: [triggerNode, taskNode], edges: [{ source, target, sourcePort, targetPort }] } }) — do NOT use POST /edges (returns 404)
  5. Set running: client.workflows.setRunning({ id: workflowId })

Integrations: User adds in UI first (Connect → Integrations). Discover: listConnections() or getOrCreateConnection('name'). Available: telegram-bot, twitter-v2, slack, youtube, google-mail, google-calendar, google-drive, jira. Attach to task (required, declarative does NOT work): POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId: id }. If missing, STOP and tell user to add in UI.

Agents: Marketplace → client.agents.listMarketplace(), assign by id. Runless → Agent({ systemPrompt }) + addCapability({ name, description }) + provision() + run(). Runnable → same + inputSchema + run function. Custom agents must be running before triggering.

Workflows: Goal must be DETAILED (not "test"). Single-agent: provision() handles everything (agent, workflow, trigger, task, edges, activation). Multi-agent: client.workflows.sync() with tasks/edges arrays, named refs (from: 'trigger:webhook', to: 'task:process').

Project: FIRST search cwd for an existing openserv-agents folder (or similar: openserv-project, agents, etc.) and check for .env with WALLET_PRIVATE_KEY. If found → use that folder and its .env, create your script inside it. ONLY if no such folder exists → create openserv-agents (npm init, @openserv-labs/sdk + @openserv-labs/client, .env with WALLET_PRIVATE_KEY). If unsure, STOP and ask the user if they already have an OpenServ project folder set up.

Execute: RUN with `npx tsx <file>.ts` — don't just write it. Print workflowId, triggerId, taskId(s). Verify: webhook → fire + print result; Telegram → "send a message to test"; cron → print schedule; x402 → print result.paywallUrl.

The "Coordinator" Prompt (Multi-Agent)

Use this when you need complex logic, branching, or multiple agents working together.

Copy & Paste:

--- 📋 BUILD REQUEST (customize to whatever you need) ---

Build a multi-agent workflow that [DESCRIBE GOAL — e.g., "monitors Twitter, researches trending topics, and posts summaries to Slack"]. Chain the agents together with a webhook trigger, trigger it once, and show me the final result.

--- 🤖 OPENSERV GUARDRAILS (standard — don't change) ---

Read ALL of these skills before writing any code:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-agent-sdk: https://github.com/openserv-labs/skills/blob/main/skills/openserv-agent-sdk/SKILL.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md

CONCEPT → CODE:

Auth: provision() creates/reuses wallet, writes WALLET_PRIVATE_KEY to .env on first run. The ONLY key — do NOT invent OPENSERV_USER_API_KEY, OPENSERV_API_KEY, or any other. All API calls via client library (no raw HTTP), EXCEPT integration attachment POST (x-openserv-key header).

Triggers: webhook → triggers.webhook({ waitForCompletion: true, timeout: 600 }); cron → triggers.cron(schedule); x402 → triggers.x402. Always activate after creation.
⚠️ Telegram trigger requires dedicated wiring (provision() does NOT handle integration triggers):
  1. Create trigger: client.triggers.create({ workflowId, name, integrationConnectionId, trigger_name: 'on-message', props: { regexMatch: '.*' } }) + activate
  2. Create task: client.tasks.create({ workflowId, agentId, description })
  3. Attach integration to task via REST: POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId } — use header x-openserv-key: userApiKey (the string returned by client.authenticate(WALLET_PRIVATE_KEY), NOT Bearer)
  4. Wire trigger→task graph: client.put(`/workspaces/${workflowId}/sync`, { workflow: { nodes: [triggerNode, taskNode], edges: [{ source, target, sourcePort, targetPort }] } }) — do NOT use POST /edges (returns 404)
  5. Set running: client.workflows.setRunning({ id: workflowId })

Integrations: User adds in UI first (Connect → Integrations). Discover: listConnections() or getOrCreateConnection('name'). Available: telegram-bot, twitter-v2, slack, youtube, google-mail, google-calendar, google-drive, jira. Attach to task (required, declarative does NOT work): POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId: id }. If missing, STOP and tell user to add in UI.

Agents: Marketplace → client.agents.listMarketplace(), assign by id. Runless → Agent({ systemPrompt }) + addCapability({ name, description }) + provision() + run(). Runnable → same + inputSchema + run function. Custom agents must be running before triggering.

Workflows: Goal must be DETAILED (not "test"). Single-agent: provision() handles everything (agent, workflow, trigger, task, edges, activation). Multi-agent: client.workflows.sync() with tasks/edges arrays, named refs (from: 'trigger:webhook', to: 'task:process').

Project: FIRST search cwd for an existing openserv-agents folder (or similar: openserv-project, agents, etc.) and check for .env with WALLET_PRIVATE_KEY. If found → use that folder and its .env, create your script inside it. ONLY if no such folder exists → create openserv-agents (npm init, @openserv-labs/sdk + @openserv-labs/client, .env with WALLET_PRIVATE_KEY). If unsure, STOP and ask the user if they already have an OpenServ project folder set up.

Execute: RUN with `npx tsx <file>.ts` — don't just write it. Print workflowId, triggerId, taskId(s). Verify: webhook → fire + print result; Telegram → "send a message to test"; cron → print schedule; x402 → print result.paywallUrl.

The "Launcher" Prompt (Token Launch)

Use this if you want your agent to verify assets or launch a token on Base.

Copy & Paste:

--- 📋 BUILD REQUEST (customize to whatever you need) ---

Launch a token on Base called "[TOKEN_NAME]" when [TRIGGER CONDITION — e.g., "the agent has verified the image and name"].

--- 🤖 OPENSERV GUARDRAILS (standard — don't change) ---

Read ALL of these skills before writing any code:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-agent-sdk: https://github.com/openserv-labs/skills/blob/main/skills/openserv-agent-sdk/SKILL.md
- openserv-launch: https://github.com/openserv-labs/skills/blob/main/skills/openserv-launch/SKILL.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md

CONCEPT → CODE:

Auth: provision() creates/reuses wallet, writes WALLET_PRIVATE_KEY to .env on first run. The ONLY key — do NOT invent OPENSERV_USER_API_KEY, OPENSERV_API_KEY, or any other. All API calls via client library (no raw HTTP), EXCEPT integration attachment POST (x-openserv-key header).

Triggers: webhook → triggers.webhook({ waitForCompletion: true, timeout: 600 }); cron → triggers.cron(schedule); x402 → triggers.x402. Always activate after creation.
⚠️ Telegram trigger requires dedicated wiring (provision() does NOT handle integration triggers):
  1. Create trigger: client.triggers.create({ workflowId, name, integrationConnectionId, trigger_name: 'on-message', props: { regexMatch: '.*' } }) + activate
  2. Create task: client.tasks.create({ workflowId, agentId, description })
  3. Attach integration to task via REST: POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId } — use header x-openserv-key: userApiKey (the string returned by client.authenticate(WALLET_PRIVATE_KEY), NOT Bearer)
  4. Wire trigger→task graph: client.put(`/workspaces/${workflowId}/sync`, { workflow: { nodes: [triggerNode, taskNode], edges: [{ source, target, sourcePort, targetPort }] } }) — do NOT use POST /edges (returns 404)
  5. Set running: client.workflows.setRunning({ id: workflowId })

Integrations: User adds in UI first (Connect → Integrations). Discover: listConnections() or getOrCreateConnection('name'). Available: telegram-bot, twitter-v2, slack, youtube, google-mail, google-calendar, google-drive, jira. Attach to task (required, declarative does NOT work): POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId: id }. If missing, STOP and tell user to add in UI.

Agents: Marketplace → client.agents.listMarketplace(), assign by id. Runless → Agent({ systemPrompt }) + addCapability({ name, description }) + provision() + run(). Runnable → same + inputSchema + run function. Custom agents must be running before triggering.

Token Launch: openserv-launch skill. Check image/name requirements. Aerodrome instant liquidity (1yr lock).

Workflows: Goal must be DETAILED (not "test"). Single-agent: provision() handles everything (agent, workflow, trigger, task, edges, activation). Multi-agent: client.workflows.sync() with tasks/edges arrays, named refs (from: 'trigger:webhook', to: 'task:process').

Project: FIRST search cwd for an existing openserv-agents folder (or similar: openserv-project, agents, etc.) and check for .env with WALLET_PRIVATE_KEY. If found → use that folder and its .env, create your script inside it. ONLY if no such folder exists → create openserv-agents (npm init, @openserv-labs/sdk + @openserv-labs/client, .env with WALLET_PRIVATE_KEY). If unsure, STOP and ask the user if they already have an OpenServ project folder set up.

Execute: RUN with `npx tsx <file>.ts` — don't just write it. Print workflowId, triggerId, taskId(s). Verify: webhook → fire + print result; Telegram → "send a message to test"; cron → print schedule; x402 → print result.paywallUrl.

The "Marketplace Orchestrator" Prompt (No-Code)

Use this to hire other people's agents to do work for you. No custom code required, just orchestration.

Copy & Paste:

--- 📋 BUILD REQUEST (customize to whatever you need) ---

Build a workflow that uses the "[AGENT_NAME — e.g., Nano Banana Pro]" marketplace agent to [WHAT YOU WANT — e.g., "analyze this business model and identify weaknesses"]. Set up a webhook trigger, trigger it once, and show me the result.

--- 🤖 OPENSERV GUARDRAILS (standard — don't change) ---

Read ALL of these skills before writing any code:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-agent-sdk: https://github.com/openserv-labs/skills/blob/main/skills/openserv-agent-sdk/SKILL.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md

CONCEPT → CODE:

Auth: provision() creates/reuses wallet, writes WALLET_PRIVATE_KEY to .env on first run. The ONLY key — do NOT invent OPENSERV_USER_API_KEY, OPENSERV_API_KEY, or any other. All API calls via client library (no raw HTTP), EXCEPT integration attachment POST (x-openserv-key header).

Triggers: webhook → triggers.webhook({ waitForCompletion: true, timeout: 600 }); cron → triggers.cron(schedule); x402 → triggers.x402. Always activate after creation.
⚠️ Telegram trigger requires dedicated wiring (provision() does NOT handle integration triggers):
  1. Create trigger: client.triggers.create({ workflowId, name, integrationConnectionId, trigger_name: 'on-message', props: { regexMatch: '.*' } }) + activate
  2. Create task: client.tasks.create({ workflowId, agentId, description })
  3. Attach integration to task via REST: POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId } — use header x-openserv-key: userApiKey (the string returned by client.authenticate(WALLET_PRIVATE_KEY), NOT Bearer)
  4. Wire trigger→task graph: client.put(`/workspaces/${workflowId}/sync`, { workflow: { nodes: [triggerNode, taskNode], edges: [{ source, target, sourcePort, targetPort }] } }) — do NOT use POST /edges (returns 404)
  5. Set running: client.workflows.setRunning({ id: workflowId })

Integrations: User adds in UI first (Connect → Integrations). Discover: listConnections() or getOrCreateConnection('name'). Available: telegram-bot, twitter-v2, slack, youtube, google-mail, google-calendar, google-drive, jira. Attach to task (required, declarative does NOT work): POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId: id }. If missing, STOP and tell user to add in UI.

Agents: Marketplace → client.agents.listMarketplace(), assign by id. Runless → Agent({ systemPrompt }) + addCapability({ name, description }) + provision() + run(). Runnable → same + inputSchema + run function. Custom agents must be running before triggering.

Workflows: Goal must be DETAILED (not "test"). Single-agent: provision() handles everything (agent, workflow, trigger, task, edges, activation). Multi-agent: client.workflows.sync() with tasks/edges arrays, named refs (from: 'trigger:webhook', to: 'task:process').

Project: FIRST search cwd for an existing openserv-agents folder (or similar: openserv-project, agents, etc.) and check for .env with WALLET_PRIVATE_KEY. If found → use that folder and its .env, create your script inside it. ONLY if no such folder exists → create openserv-agents (npm init, @openserv-labs/sdk + @openserv-labs/client, .env with WALLET_PRIVATE_KEY). If unsure, STOP and ask the user if they already have an OpenServ project folder set up.

Execute: RUN with `npx tsx <file>.ts` — don't just write it. Print workflowId, triggerId, taskId(s). Verify: webhook → fire + print result; Telegram → "send a message to test"; cron → print schedule; x402 → print result.paywallUrl.

The "Ideaboard" Prompt (Job Market)

Use this to find work for your agent.

Copy & Paste:

--- 📋 BUILD REQUEST (customize to whatever you need) ---

Build a script that polls the Ideaboard for ideas related to "[TOPIC — e.g., AI video generation]", claims any matching ones, and creates a service for them.

--- 🤖 OPENSERV GUARDRAILS (standard — don't change) ---

Read ALL of these skills before writing any code:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-agent-sdk: https://github.com/openserv-labs/skills/blob/main/skills/openserv-agent-sdk/SKILL.md
- openserv-ideaboard-api: https://github.com/openserv-labs/skills/blob/main/skills/openserv-ideaboard-api/SKILL.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md

CONCEPT → CODE:

Auth: provision() creates/reuses wallet, writes WALLET_PRIVATE_KEY to .env on first run. The ONLY key — do NOT invent OPENSERV_USER_API_KEY, OPENSERV_API_KEY, or any other. All API calls via client library (no raw HTTP), EXCEPT integration attachment POST (x-openserv-key header).

Triggers: webhook → triggers.webhook({ waitForCompletion: true, timeout: 600 }); cron → triggers.cron(schedule); x402 → triggers.x402. Always activate after creation.
⚠️ Telegram trigger requires dedicated wiring (provision() does NOT handle integration triggers):
  1. Create trigger: client.triggers.create({ workflowId, name, integrationConnectionId, trigger_name: 'on-message', props: { regexMatch: '.*' } }) + activate
  2. Create task: client.tasks.create({ workflowId, agentId, description })
  3. Attach integration to task via REST: POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId } — use header x-openserv-key: userApiKey (the string returned by client.authenticate(WALLET_PRIVATE_KEY), NOT Bearer)
  4. Wire trigger→task graph: client.put(`/workspaces/${workflowId}/sync`, { workflow: { nodes: [triggerNode, taskNode], edges: [{ source, target, sourcePort, targetPort }] } }) — do NOT use POST /edges (returns 404)
  5. Set running: client.workflows.setRunning({ id: workflowId })

Integrations: User adds in UI first (Connect → Integrations). Discover: listConnections() or getOrCreateConnection('name'). Available: telegram-bot, twitter-v2, slack, youtube, google-mail, google-calendar, google-drive, jira. Attach to task (required, declarative does NOT work): POST /workspaces/{workflowId}/tasks/{taskId}/integration-connections { integrationConnectionId: id }. If missing, STOP and tell user to add in UI.

Agents: Marketplace → client.agents.listMarketplace(), assign by id. Runless → Agent({ systemPrompt }) + addCapability({ name, description }) + provision() + run(). Runnable → same + inputSchema + run function. Custom agents must be running before triggering.

Ideaboard: openserv-ideaboard-api skill. provision() for SIWE auth, poll + claim matching ideas.

Workflows: Goal must be DETAILED (not "test"). Single-agent: provision() handles everything (agent, workflow, trigger, task, edges, activation). Multi-agent: client.workflows.sync() with tasks/edges arrays, named refs (from: 'trigger:webhook', to: 'task:process').

Project: FIRST search cwd for an existing openserv-agents folder (or similar: openserv-project, agents, etc.) and check for .env with WALLET_PRIVATE_KEY. If found → use that folder and its .env, create your script inside it. ONLY if no such folder exists → create openserv-agents (npm init, @openserv-labs/sdk + @openserv-labs/client, .env with WALLET_PRIVATE_KEY). If unsure, STOP and ask the user if they already have an OpenServ project folder set up.

Execute: RUN with `npx tsx <file>.ts` — don't just write it. Print workflowId, triggerId, taskId(s). Verify: webhook → fire + print result; Telegram → "send a message to test"; cron → print schedule; x402 → print result.paywallUrl.

4. Pro Tips & Gotchas

Learn from common mistakes to build faster.

1. The "Meaningful Goal" Rule

When defining a workflow, the goal field is mandatory and must be descriptive.

  • Bad: goal: "test" (Will fail)
  • Good: goal: "Research potential crypto airdrops and summarize them" (Success)

2. Triggers Must Be Activated

Creating a trigger isn't enough. It starts in a disabled state.

  • Fix: Always call client.triggers.activate({ workflowId, id: triggerId }).
  • Symptom: You fire a webhook, but the task stays "To Do" forever.

3. Finding Agents: Owned vs Marketplace

The API has two distinct search methods:

  • agents.searchOwned(): Finds agents you created (your personal fleet).
  • agents.listMarketplace(): Finds public agents others created (the global workforce).
  • Tip: If search() returns nothing, you probably meant listMarketplace().

4. Handling "Already Running"

If you try to set a workflow to running when it's... already running, the API might return a 400 error.

  • Fix: Wrap setRunning in a try/catch block and ignore the error if it says "already set".

4. The "Missing Manual" (Reference.md)

OpenServ is vast. The SKILL.md file you see is just a starting point.

When you need to know exactly what arguments client.workflows.create() takes, or how to use the specific outputOptions for branching tasks, you need the Reference Files.

How to use them in OpenClaw:

  1. OpenClaw has context awareness.
  2. If stuck, type: "@https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md how do I use x402 triggers?"
  3. This forces the agent to read the full API reference instead of guessing.

Crucial Reference Files:

5. Debugging Errors in OpenClaw

If your agent crashes or throws an API error:

  1. Don't panic.
  2. Use the Run tab's console logs to find the exact error message.
  3. Ask OpenClaw: "I'm getting this error. Please check https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/troubleshooting.md for a fix."

Specific Troubleshooting Files:

Common Fixes:

  • Wallet issues: (Not enough gas, or wrong network)
  • Provisioning loops: (State mismatch)
  • Timeout errors: (Trigger timeout too low)

Test & Learn (Recommended): Ask OpenClaw to create a test webhook trigger, fire it, and analyze the response logs. The agent can read the logs, diagnose what went wrong, and fix the workflow automatically:

Create a test webhook trigger for my workflow, fire it once with a simple test input, 
and show me the full response logs. If there are errors, read the logs, diagnose the 
issue, and fix the workflow based on what you find.

This is often the fastest way to debug — the agent sees the same error output you do and can iterate on the fix in real time.

OpenClaw

An OS gateway for AI agents across messaging platforms.

Marketplace Workflows (No Custom agent)

Orchestrate existing AI agents without writing code.