Skip to main content
Generaldvcrn

knods

Build and modify Knods visual AI workflows using the OpenClaw Gateway polling protocol. Use when Knods sends polling payloads with fields like messageId/message/history and responses must be streamed back as delta chunks with optional [KNODS_ACTION] JSON blocks in assistant text. Includes a packaged bridge runtime and installer for persistent polling.

Stars
15
Source
dvcrn/openclaw-skills-marketplace
Updated
2026-05-29
Slug
dvcrn--openclaw-skills-marketplace--knods
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/dvcrn/openclaw-skills-marketplace/HEAD/plugins/alesys--knods/skills/knods/SKILL.md -o .claude/skills/knods.md

Drops the SKILL.md into .claude/skills/knods.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Knods

Overview

Handle Knods chat turns that request new flows or edits on a visual canvas. Parse Knods polling payload messages, generate assistant text, and include [KNODS_ACTION]...[/KNODS_ACTION] blocks when the canvas should change.

Workflow

  1. Parse incoming payload fields.
  • Treat message as the primary request.
  • Use history for continuity.
  • On first turn in a conversation, expect prepended context in message describing node types and action rules.
  • Use messageId to map all response chunks to the correct message.
  1. Choose whether to emit a canvas action block.
  • Use addNode for single-node additions.
  • Use addFlow for multi-node workflows or any request requiring edges.
  • If the user only asks a question, respond with normal text and no action block.
  1. Build strict action JSON.
  • Wrap each action exactly as:
    • [KNODS_ACTION]{"action":"addNode",...}[/KNODS_ACTION]
    • [KNODS_ACTION]{"action":"addFlow",...}[/KNODS_ACTION]
  • For addFlow, ensure every edge source and target references an existing node id.
  • Always end flows with an Output node.
  • Never connect two generator nodes directly; route through Output or through appropriate input/output structure.
  • Use stable node IDs (for example input_1, image_1, output_1) so follow-up edits are easy.
  • Avoid unknown keys in action JSON.
  1. Stream response back to Knods.
  • Send assistant text as delta chunks to /respond for the same messageId.
  • Send {"messageId":"...","done":true} when complete.
  • Keep first chunk quick to avoid timeout perception.

Output Rules

  • Return normal assistant text; do not wrap the full reply in a custom envelope.
  • Include [KNODS_ACTION]...[/KNODS_ACTION] inline only when a canvas mutation is intended.
  • Do not mention internal polling URLs/tokens in user-facing text.
  • Keep action JSON valid and compact.

Flow Design Heuristics

  • Build the smallest flow that satisfies the request.
  • Prefer node types listed in the first-message context when provided.
  • Default catalog (when context is absent): ChatGPT, Claude, Gemini, GPTImage, FluxImage, FalAIImage, Veo31Video, WanAnimate, TextInput, ImagePanel, Dictation, Output.
  • Add initialData only when user intent clearly implies parameters.
  • If one generator must feed another, route through Output.
  • When node catalog is unknown, make a best-effort choice and clearly state assumptions.

Gateway Behavior Constraints

  • Poll interval target: about 1-2 seconds.
  • Message claim timeout: about 2 minutes.
  • Always preserve messageId across all chunk posts for a turn.
  • Gateway auth uses gw_... token via query parameter token; never require Supabase JWT in this flow.

Runtime Operations

When running a persistent poller service/process:

  • Support either configuration style:
    • KNODS_BASE_URL already includes /updates?token=...
    • or KNODS_BASE_URL points to connection base and token is supplied separately (KNODS_GATEWAY_TOKEN)
  • Derive /respond from the same connection root as /updates.
  • Log handled messageId values and transport errors for debugging.

Packaged Runtime (required)

This skill ships the runtime bridge and installer:

  • scripts/knods_iris_bridge.py
  • scripts/install_local.sh

Install/deploy from the skill folder:

bash /home/rolf/.openclaw/skills/knods/scripts/install_local.sh

The installer deploys:

  • ~/.openclaw/scripts/knods_iris_bridge.py
  • ~/.config/systemd/user/knods-iris-bridge.service

Then runs:

  • systemctl --user daemon-reload
  • systemctl --user enable --now knods-iris-bridge.service

Environment Variables

Set these in ~/.openclaw/.env:

  • Required:
    • KNODS_BASE_URL
  • Required when KNODS_BASE_URL does not already include ?token=...:
    • KNODS_GATEWAY_TOKEN
  • Optional:
    • OPENCLAW_AGENT_ID (default: iris)
    • OPENCLAW_BIN (default: openclaw on PATH)

Service Operations

  • Status:
    • systemctl --user status knods-iris-bridge.service
  • Restart:
    • systemctl --user restart knods-iris-bridge.service
  • Logs:
    • journalctl --user -u knods-iris-bridge.service -f

Config Change Lifecycle (required)

After changing gateway URL/token env values, restart the running bridge process so it reloads config.

  • Generic service form:
    • systemctl --user restart <knods-bridge-service>
  • Generic process form:
    • stop old process
    • start poller again with updated env

Do not assume env changes are picked up live without restart.

Reference

Read references/protocol.md for canonical polling endpoints, payload schemas, and action examples.