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 repo session clone; 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.

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 repo session is reused by default and fast-forward syncs against the remote branch when the canvas/session is re-opened.
  2. Ask for changes in the global chat. Website code changes edit the active 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 same shared repo or isolated checkout. force_new_session always creates a fresh isolated checkout even if the caller supplied an existing session. 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.

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.
  • Instances remain fully capable by default. If a Hub administrator explicitly disables that instance's Shell tools capability, Website Canvas read-only settings/session/status access remains available, while session 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.
  • Repo session root: /app/workspace/.website-canvas/sessions.
  • 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 active session 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/:id
  • GET /preview/:sessionId/: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.