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

1. Always use unique IDs — Each widget needs a distinct id
2. Keep options concise — Button labels should be short
3. Use widgets for structured input — Better than "type 1, 2, or 3"
4. 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

Section	Meaning
Active	Currently working on — doing NOW
Blocked	Waiting for input/dependency
Backlog	Will work on later
Done	Completed (hidden in UI)

Task Icons

Icon	Meaning
🟡	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.

State	Purpose	Design Ideas
idle	Default, waiting	Breathing, looking around, show-off poses, occasional blink
thinking	Processing request	Head tilt, eyes up, thought bubble (❓), tapping foot/wing
talking	Delivering response	Mouth animation, speech bubble, music notes (🎵), gesturing
listening	User is speaking	Leaning forward, BIG attentive eyes, ears/crest perked
working	Extended task	Laptop/tools visible, typing motion, focused squint
happy	Positive outcome	Bouncing, hearts (❤️), squinty smile eyes (^_^), wagging
celebrating	Major success	Jumping, spinning, confetti (⭐), maximum energy
sleeping	Inactive/idle timeout	Eyes closed, Z's floating (💤), curled up, slow breathing
error	Something went wrong	Shaking, exclamation (❗), ruffled, sweat drop, red tint
reflecting	Thoughtful moment	Light bulb (💡), gazing upward, calm pose, one hand raised

State Design Principles

1. Visual indicators matter — Add floating symbols (❓❤️💡❗💤⭐) that appear per-state
2. Body language is key — Each state needs distinct posture, movement speed, and energy level
3. Eyes tell the story — Big/small, open/closed, squinty/wide, pupil direction
4. Movement rhythm varies — Fast/bouncy for happy, slow/gentle for sleeping, shaky for error
5. Props add clarity — Laptop for working, floating Z's for sleeping, confetti for celebrating
6. 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

Path	Purpose
~/.clawtime/.env	Secrets & config
~/.clawtime/config.json	Avatar selection, preferences
~/.clawtime/credentials.json	Passkey data
~/.clawtime/sessions.json	Active sessions
~/.clawtime/avatars/	Custom avatars
~/.clawtime/tasks.json	Task list

Troubleshooting

See INSTALL.md → Troubleshooting for common issues.