Clapilot Docs
Docs

Website Canvas

Bundled website module: repo-backed editing, preview, and publish flow.

What it does

Website Canvas (website-canvas) edits a client website against a GitHub repository with live preview. Change requests run through the global chat and are applied as direct local edits in a single shared repo checkout; publishing to main is an explicit module action. The agent shares the exact same backend path via native tools, so voice, chat, and background runs all edit the same clone.

The instance keeps exactly one local checkout of the configured repo at any time. Every user of the Clapilot instance sees and works on that same checkout — there are no per-user sessions, no isolated clones, and no session IDs to manage. The checkout has a stable deterministic ID derived from the repo, survives process restarts via its on-disk metadata, and stale or replaced clone directories are cleaned up automatically.

How to open / enable it

  • Open the module from the Clapilot module menu; the route is /modules/website-canvas.
  • Requires a valid selected GitHub integration for repo operations. The module reads global website settings plus the selected named GitHub integration from app_settings.
  • Manifest: bundled-modules/website-canvas/module.json (slug website-canvas, entry index.html, renderer react, icon globe). The React UI is src/components/modules/website-canvas-module.tsx, hosted by src/app/(app)/modules/[slug]/page.tsx; the bundled frontend assets remain in bundled-modules/website-canvas/ but the app renders the module directly in the main React tree.
  • The React host keeps the configuration UI compact: a top configuration bar above the preview, save / reload / open actions, plus an explicit Veröffentlichen action.

Key workflows

Edit the website

  1. Open the module; the shared checkout is reused by default and fast-forward syncs against the remote branch when the canvas is re-opened.
  2. Ask for changes in the global chat. Website code changes edit the shared repo clone locally by default — no feature branches, no pull requests, and no auto-publish unless publishing is explicitly requested.
  3. Preview updates through the module preview path (/preview/...); preview URLs are rewritten for asset paths.
  4. For larger or clearly multi-step requests, Website Canvas may escalate internally to the Website Canvas-linked interactive Agent Orchestrator session, but that session still edits the same repo clone and must not create a PR or switch branches. If the Agent Orchestrator or Codex app-server path is unavailable, Website Canvas stays on the direct local coding-provider path instead of failing over to detached PR-oriented flows.
  5. Agent-triggered ensure/apply calls return an operation ID before clone, sync, or provider work begins. Poll website_get_operation until it reports succeeded or failed; each poll waits up to 20 seconds for completion before returning an in-progress state, and native provider loops permit at most 60 of these passive polls (covering the 20-minute operation window). Retry the original call with the same idempotency key, caller, and payload to recover the active operation without duplicate edits. One checkout-scoped queue serializes agent operations with direct ensure/sync/chat/commit/push requests against the shared repo checkout. force_new_session discards the shared checkout and re-clones it fresh (uncommitted local changes are lost); it never creates a second parallel checkout. Completed results remain queryable for eight hours. Failed operations release their keys immediately for a real retry; successful operations keep a five-minute deduplication window before a later intentional repeat can run again.

Publish

  • Veröffentlichen uses the module publish path to commit and push the active Website Canvas state directly to main.

Sync

  • Explicit syncs are available through POST /sync and the website_sync_repo tool; they skip dirty worktrees unless the caller explicitly asks to discard local changes.
  • The linked interactive coding session is reused while the repo clone stays valid; if the clone is recreated after sync conflict/divergence handling, Website Canvas starts a fresh interactive coding session against the new clone automatically. Replaced clone directories are deleted right after the fresh clone succeeds, so only one checkout exists on disk.

How the agent can drive it (tools)

Native ClapilotAICore tools mirror the main Website Canvas workflow:

  • website_get_settings
  • website_ensure_session
  • website_apply_change
  • website_get_operation
  • website_commit_changes
  • website_push_changes
  • website_commit_and_push
  • website_get_session
  • website_sync_repo

Notes:

  • Live voice/chat and native background/channel runs share the same Website Canvas backend path as the module UI; everything operates on the one shared checkout.
  • session_id parameters are optional stable checkout ids kept for compatibility; commit/push/approve and website_get_session resolve the shared checkout from the configured repo when the id is omitted or stale.
  • Instances remain fully capable by default. If a Hub administrator explicitly disables that instance's Shell tools capability, Website Canvas read-only settings/checkout/status access remains available, while checkout creation, code changes, sync, commit, and push are rejected at both the agent tool proxy and direct module API boundary.
  • The coding session is instructed to leave website edits local by default: no feature branches or pull requests, and no auto-publish after a change request unless publishing is explicitly requested.
  • The module can invoke skill context from /app/workspace/skills/clapilot-client-website-manager/SKILL.md.
  • The module uses the module runtime API contract only (no direct app route creation).

Configuration & limits

  • GitHub integration: a valid selected named GitHub integration is required for all repo operations.
  • Checkout root: /app/workspace/.website-canvas/sessions. Only one checkout lives there at a time; stale, archived, and legacy per-user clone directories are pruned automatically.
  • Module preferences are stored under the compatibility state path /home/node/.openclaw/agents/main/agent/website-canvas.
  • Small/medium changes prefer direct local edits inside the shared clone; escalation to the linked interactive Agent Orchestrator session is internal and reserved for larger multi-step changes.

API endpoints exposed by module

Base: /api/modules/website-canvas/api — implementation: bundled-modules/website-canvas/api/handler.mjs.

  • GET /health
  • GET /settings
  • POST /settings
  • POST /repos
  • POST /session/ensure
  • POST /operation/ensure (requires idempotencyKey, returns HTTP 202 plus an operation ID)
  • POST /operation/apply (requires idempotencyKey, returns HTTP 202 plus an operation ID)
  • GET /operation/:operationId (states: queued, running, succeeded, failed; an unknown ID returns not_started; optional waitMs is clamped to 20 seconds)
  • GET /session/current (shared checkout of the configured repo)
  • GET /session/:id
  • GET /preview/:checkoutId/:path*
  • POST /chat
  • POST /sync
  • POST /commit
  • POST /push
  • POST /approve

Troubleshooting

  • Repo actions fail: check that the selected named GitHub integration in app_settings is valid and has access to the repository.
  • Preview shows stale content after remote changes: re-open the canvas (triggering the fast-forward sync) or run an explicit POST /sync / website_sync_repo; dirty worktrees are skipped unless local changes are explicitly discarded.