# Knods

> Builds and modifies Knods visual AI workflows by parsing polling payloads, generating assistant text, and streaming responses with optional canvas action blocks.

- Skill: `dvcrn/knods` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add dvcrn/knods`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/knods/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Integrations & APIs, API Design
- Tags: Bridge Runtime, Canvas Actions, Gateway, Knods, Polling Protocol, Systemd, Visual Ai Workflows
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/dvcrn/knods

---


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

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",...}[/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.

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.

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