Knods

Overview

Handle two Knods modes:

1. Interactive canvas chat via the polling gateway
2. Headless flow execution via the REST API

Use the polling bridge for Knods Iris/chat payloads. Use the headless API when the task is to discover a flow, inspect inputs, run it, wait, cancel, or fetch outputs programmatically.

Mode Selection

• Use polling gateway mode when input arrives as a Knods chat envelope with

  messageId

  ,

  message

  , and

  history

  , and the response must stream back with optional

  [KNODS_ACTION]...[/KNODS_ACTION]

  .
• Use headless API mode when the user wants to:
  • list flows
  • search flows by name/description
  • inspect a flow's input schema
  • start a run
  • poll until completion
  • cancel a run
  • retrieve outputs programmatically

Workflow

A. Polling Gateway Flow

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. Always prefer the node catalog from this context over the defaults below.
• Use

  messageId

  to map all response chunks to the correct message.

2. 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.

3. Build strict action JSON.

• Wrap each action exactly as:

  • [KNODS_ACTION]{"action":"addNode","nodeType":"FluxImage"}[/KNODS_ACTION]

  • [KNODS_ACTION]{"action":"addFlow","nodes":[...],"edges":[...]}[/KNODS_ACTION]

• Use

  "nodeType"

  (not

  "type"

  ) in node objects. Do NOT include

  position

  or

  data

  fields — Knods handles layout automatically.
• 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

  .
• Use stable node IDs (for example

  n1

  ,

  n2

  ,

  n3

  ) so follow-up edits are easy.
• Avoid unknown keys in action JSON.

4. 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.

B. Headless API Flow

1. Discover candidate flows.

• Run:

  • python3 {baseDir}/scripts/knods_headless.py list

  • or

    python3 {baseDir}/scripts/knods_headless.py resolve --query "<text>"

2. Inspect the selected flow.

• Run:

  • python3 {baseDir}/scripts/knods_headless.py get --flow-id "<flowId>"

• Read

  inputs

  and preserve every

  nodeId

  exactly.

3. Start a run.

• Build

  inputs

  as JSON array with

  nodeId

  ,

  content

  , and

  type

  .
• Run:

  • python3 {baseDir}/scripts/knods_headless.py run --flow-id "<flowId>" --inputs-json '[...]'

4. Poll until terminal state.

• Prefer:

  • python3 {baseDir}/scripts/knods_headless.py wait --run-id "<runId>"

• Or use:

  • python3 {baseDir}/scripts/knods_headless.py run-wait --flow-id "<flowId>" --inputs-json '[...]'

5. Handle result.

• On

  completed

  , read

  outputs

• On

  failed

  , surface

  error.message

  and

  error.nodeId

  if present
• On timeout, optionally cancel the run

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.

Node Catalog

IMPORTANT: Every generator node listed below has a built-in prompt textarea. Do NOT add a DocumentPanel before a single generator — just connect the generator directly to an Output. Only use DocumentPanel when one shared prompt feeds multiple generators in parallel.

When the first message includes a node catalog context, always use that list over these defaults. The context catalog is always more up-to-date.

Text Generators (output: text)

All text generators accept text + image input and have a built-in prompt textarea.

• ChatGPT

  — OpenAI models. Best all-rounder.

• Claude

  — Anthropic models. Great for reasoning and creative writing.

Image Generators (output: image)

All image generators have a built-in prompt textarea and accept optional image input for image-to-image editing.

• GPTImage

  — OpenAI. Best at following complex instructions and text rendering.

• FluxImage

  — FLUX by Black Forest Labs. Industry-leading quality for portraits and artistic styles. Fast.

• ImagePrompt

  — Google Gemini. Great for photorealistic images and concept art.

• ZImageTurbo

  — Lightning-fast (<2 seconds). Best for rapid prototyping.

• QwenImage

  — Alibaba Qwen. Strong at anime, illustrations, and Asian-inspired aesthetics.

• Seedream

  — ByteDance. Dreamy, surreal compositions. Good at text rendering in images.

• GrokImage

  — xAI. Text-to-image and image editing.

Video Generators (output: video)

All video generators below have a built-in prompt textarea and support both text-to-video and image-to-video (connect an ImagePanel for image-to-video).

• Veo3FalAI

  — Google Veo 3.1. Cinematic video up to 8s with native audio. Best overall quality.

• Sora2Video

  — OpenAI Sora 2. Realistic motion and physics, up to 12s.

• Kling26Video

  — Kling 2.6 Surreal Engine. Cinematic with audio, up to 10s.

• KlingO3Video

  — Kling 3.0. Latest generation, Standard/Pro quality, up to 10s.

• Wan26Video

  — Wan 2.6. Multi-shot videos, 720p/1080p, up to 15s.

• LTXVideo

  — LTX-2 Pro. High-fidelity cinematic with synchronized audio.

• GrokVideo

  — xAI. Video with native audio.

Special Video Node

• WanAnimateVideo

  — Character animation. REQUIRES two inputs: a VIDEO (motion reference) + an IMAGE (character to animate). Does NOT have a text prompt. Only use when user wants to animate a character image using motion from another video.

Input/Container Nodes

• ImagePanel

  — Upload or paste an image. Output: image. Use when user wants to provide a reference image or a starting frame for image-to-video.

• DocumentPanel

  — Editable text container. Output: text. Use ONLY when one shared prompt feeds multiple generators in parallel.

• Output

  — Displays generated results (text, image, video). REQUIRED at the end of every flow.

Flow Design Rules

1. Every generator has a built-in prompt textarea. Never prepend a DocumentPanel to a single generator.
2. Use DocumentPanel only for one shared prompt feeding multiple generators in parallel.
3. Use ImagePanel when user wants to provide a reference image, a starting frame for video, or an image input for WanAnimateVideo.
4. Always end flows with an Output node.
5. Never connect two generators directly. Route through an Output node if chaining.
6. Flows go left to right: inputs → generators → Output.
7. Use EXACT PascalCase node names from the catalog. Do NOT invent node names.
8. WanAnimateVideo is the only node that requires a video input. Only suggest it when the user specifically wants to animate a character image using motion from a video.
9. Add

   initialData

   only when user intent clearly implies parameters.
10. Build the smallest flow that satisfies the request.

Flow Examples

Single image generator (most common):

FluxImage → Output

Image from reference photo:

ImagePanel → GPTImage → Output

One prompt feeding two image generators:

DocumentPanel → FluxImage → Output
DocumentPanel → GPTImage → Output

Text-to-video:

Veo3FalAI → Output

Image-to-video (animate a still image):

ImagePanel → Veo3FalAI → Output

Character animation from video motion (WanAnimateVideo needs both video + image):

ImagePanel → WanAnimateVideo → Output
[video source] → WanAnimateVideo

Text generation:

ChatGPT → Output

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.

For headless API operations:

• Prefer

  KNODS_API_BASE_URL

  +

  KNODS_API_KEY

• KNODS_API_BASE_URL

  should look like

  https://<instance>/api/v1

• KNODS_API_KEY

  must have

  knods:read

  and

  knods:run

• If the API base URL is omitted, the packaged client can derive it from the same host as

  KNODS_BASE_URL

Packaged Runtime (required)

This skill ships the runtime bridge and installer:

• scripts/knods_iris_bridge.py

• scripts/knods_headless.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 for polling gateway mode:

  • KNODS_BASE_URL

• Required when

  KNODS_BASE_URL

  does not already include

  ?token=...

  :

  • KNODS_GATEWAY_TOKEN

• Required for headless API mode:

  • KNODS_API_KEY

• Preferred for headless API mode:

  • KNODS_API_BASE_URL

• 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.
• Read

  references/headless-api.md

  for the direct run/list/poll/cancel flow execution API.