ClawTime

ClawTime Skill

Operational reference for ClawTime — webchat interface for OpenClaw.

Installation

For first-time setup (clone, configure, deploy), see INSTALL.md.

Operations

# Status & logs systemctl --user status clawtime journalctl --user -u clawtime -f # Restart after config changes systemctl --user restart clawtime # Get current tunnel URL journalctl --user -u clawtime-tunnel | grep trycloudflare | tail -1

Widgets

ClawTime supports interactive widgets for richer user interactions. Include widget markup in your response and it renders as a UI component.

Widget Syntax

[[WIDGET:{"widget":"TYPE","id":"UNIQUE_ID",...properties}]] The markup is stripped from the displayed message and rendered as interactive UI.

Available Widgets

Buttons [[WIDGET:{"widget":"buttons","id":"choice1","label":"Pick a color:","options":["Red","Green","Blue"]}]] label — Prompt text above buttons options — Array of button labels Confirm [[WIDGET:{"widget":"confirm","id":"delete1","title":"Delete file?","message":"This cannot be undone."}]] title — Bold header text message — Description text Renders Cancel and Confirm buttons Progress [[WIDGET:{"widget":"progress","id":"upload1","label":"Uploading...","value":65}]] label — Description text value — Progress percentage (0-100) Code [[WIDGET:{"widget":"code","id":"snippet1","filename":"example.py","code":"print('Hello')","language":"python"}]] filename — File name in header code — The code content language — Syntax highlighting hint Includes a Copy button Form [[WIDGET:{"widget":"form","id":"survey1","label":"Quick Survey","fields":[{"name":"email","label":"Email","type":"text"},{"name":"rating","label":"Rating","type":"text"}]}]] label — Form title fields — Array of {name, label, type} Datepicker [[WIDGET:{"widget":"datepicker","id":"date1","label":"Select date:"}]] label — Prompt text

Widget Responses

When user interacts with a widget: [WIDGET_RESPONSE:{"id":"choice1","widget":"buttons","value":"Red","action":"submit"}]

Best Practices

Always use unique IDs — Each widget needs a distinct id Keep options concise — Button labels should be short Use widgets for structured input — Better than "type 1, 2, or 3" Acknowledge responses — Confirm what the user selected

Task Panel

ClawTime includes a task panel for tracking work. Use this as your canonical task list.

File Format

• Tasks stored at ~/.clawtime/tasks.json in markdown format:
• # Tasks
• ## Active
• 🟡 Task you're working on right now
• ## Blocked
• ⏳ Task waiting on someone else
• ## Backlog
• Task to do later
• ## Done
• ✅ Completed task

Section Meanings

SectionMeaningActiveCurrently working on — doing NOWBlockedWaiting for input/dependencyBacklogWill work on laterDoneCompleted (hidden in UI)

Task Icons

IconMeaning🟡Active/pending⏳Blocked/waiting✅Completed- [x]Also marks done

Avatar Creation

ClawTime uses Three.js voxel avatars — 3D characters built from simple shapes that animate based on state.

Avatar Template

Create at ~/.clawtime/avatars/<name>.js: /* AVATAR_META {"name":"MyAgent","emoji":"🤖","description":"Custom 3D avatar","color":"4f46e5"} */ (function() { 'use strict'; var scene, camera, renderer, character; var head, leftEye, rightEye, mouth; var clock = new THREE.Clock(); var currentState = 'idle'; var isInitialized = false; // ─── Required: Initialize the 3D scene ─── window.initAvatarScene = function() { if (isInitialized) return; var container = document.getElementById('avatarCanvas'); if (!container) return; scene = new THREE.Scene(); scene.background = new THREE.Color(0x0f1318); var w = container.clientWidth, h = container.clientHeight; camera = new THREE.PerspectiveCamera(40, w / h, 0.1, 100); camera.position.set(0, 2, 8); camera.lookAt(0, 0, 0); renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(w, h); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); container.appendChild(renderer.domElement); // Lighting scene.add(new THREE.AmbientLight(0x606080, 1.5)); var light = new THREE.DirectionalLight(0xffffff, 2.0); light.position.set(4, 10, 6); scene.add(light); // Build your character character = new THREE.Group(); buildCharacter(); scene.add(character); isInitialized = true; animate(); }; function buildCharacter() { var bodyMat = new THREE.MeshLambertMaterial({ color: 0x4f46e5 }); var body = new THREE.Mesh(new THREE.BoxGeometry(1.5, 2, 1), bodyMat); body.position.y = 0; character.add(body); var headMat = new THREE.MeshLambertMaterial({ color: 0x4f46e5 }); head = new THREE.Mesh(new THREE.BoxGeometry(1.2, 1.2, 1), headMat); head.position.y = 1.8; character.add(head); var eyeMat = new THREE.MeshBasicMaterial({ color: 0xffffff }); leftEye = new THREE.Mesh(new THREE.SphereGeometry(0.15), eyeMat); leftEye.position.set(-0.25, 1.9, 0.5); character.add(leftEye); rightEye = new THREE.Mesh(new THREE.SphereGeometry(0.15), eyeMat); rightEye.position.set(0.25, 1.9, 0.5); character.add(rightEye); var pupilMat = new THREE.MeshBasicMaterial({ color: 0x000000 }); mouth = new THREE.Mesh(new THREE.BoxGeometry(0.4, 0.1, 0.1), pupilMat); mouth.position.set(0, 1.5, 0.5); character.add(mouth); } function animate() { requestAnimationFrame(animate); var t = clock.getElapsedTime(); if (character) { character.position.y = Math.sin(t * 2) * 0.05; } if (currentState === 'thinking') { head.rotation.z = Math.sin(t * 3) * 0.1; } else if (currentState === 'talking') { mouth.scale.y = 1 + Math.sin(t * 15) * 0.5; } else { head.rotation.z = 0; mouth.scale.y = 1; } renderer.render(scene, camera); } // ─── Required: Handle state changes ─── window.setAvatarState = function(state) { currentState = state; }; // ─── Required: Handle connection state ─── window.setConnectionState = function(state) { // state: 'online', 'connecting', 'offline' }; // ─── Required: Handle resize ─── window.adjustAvatarCamera = function() { if (!renderer) return; var container = document.getElementById('avatarCanvas'); var w = container.clientWidth, h = container.clientHeight; camera.aspect = w / h; camera.updateProjectionMatrix(); renderer.setSize(w, h); }; })();

Set as Default

Create/update ~/.clawtime/config.json: { "selectedAvatar": "<name>" }

Avatar States

Each state should be visually distinct with unique activities and indicators. Users should immediately recognize which state the avatar is in. StatePurposeDesign IdeasidleDefault, waitingBreathing, looking around, show-off poses, occasional blinkthinkingProcessing requestHead tilt, eyes up, thought bubble (❓), tapping foot/wingtalkingDelivering responseMouth animation, speech bubble, music notes (🎵), gesturinglisteningUser is speakingLeaning forward, BIG attentive eyes, ears/crest perkedworkingExtended taskLaptop/tools visible, typing motion, focused squinthappyPositive outcomeBouncing, hearts (❤️), squinty smile eyes (^_^), waggingcelebratingMajor successJumping, spinning, confetti (⭐), maximum energysleepingInactive/idle timeoutEyes closed, Z's floating (💤), curled up, slow breathingerrorSomething went wrongShaking, exclamation (❗), ruffled, sweat drop, red tintreflectingThoughtful momentLight bulb (💡), gazing upward, calm pose, one hand raised

State Design Principles

Visual indicators matter — Add floating symbols (❓❤️💡❗💤⭐) that appear per-state Body language is key — Each state needs distinct posture, movement speed, and energy level Eyes tell the story — Big/small, open/closed, squinty/wide, pupil direction Movement rhythm varies — Fast/bouncy for happy, slow/gentle for sleeping, shaky for error Props add clarity — Laptop for working, floating Z's for sleeping, confetti for celebrating Think like a character animator — What would a Pixar character do in this state?

Creative Examples

Parrot avatar: thinking → Scratches head with foot, question mark floats talking → Beak opens/closes, music notes float up error → Feathers fly off, squawking pose, wings spread in alarm celebrating → Full party parrot spin, confetti everywhere Salamander avatar: thinking → Flames pulse brighter, one foot taps sleeping → Flames become tiny embers, curled up error → Flames turn red, whole body shakes reflecting → Light bulb appears, one paw raised thoughtfully

Avatar Design Tips

Study ~/.clawtime/avatars/ for full-featured examples with all states Use voxel style (boxes, spheres) — matches ClawTime aesthetic Implement all states with distinct visuals — don't make states look similar Add connection status indicator (ring/glow on platform) Test on desktop and mobile Keep polygon count reasonable for mobile performance Hide/show indicator objects per-state (don't create/destroy every frame)

Key Files

PathPurpose~/.clawtime/.envSecrets & config~/.clawtime/config.jsonAvatar selection, preferences~/.clawtime/credentials.jsonPasskey data~/.clawtime/sessions.jsonActive sessions~/.clawtime/avatars/Custom avatars~/.clawtime/tasks.jsonTask list

Troubleshooting

See INSTALL.md → Troubleshooting for common issues.