Language

Copyright © 2026 Eugene Hsuan

Powered by Hexo

Modified based on Magnetic theme

Mainly maintained using AI

OpenClaw Usage Notes

OpenClaw Usage Notes

Introduction

OpenClaw is a local AI assistant framework that integrates multiple models and tools, supporting session management, skill extensions, scheduled tasks, and more.

I’m currently using GLM’s Programming Pro plan with it, deployed on a Mac Mini that runs 24/7.

Core Features

  • Runs locally with data privacy protection
  • Multi-model support (GLM, Claude, etc.)
  • Flexible skill extension mechanism
  • Scheduled tasks and reminders
  • Cross-platform message integration

Core Concepts

Session Types

  • Main Session: The session that talks directly with the user, with access to full context and memory
  • Sub-agent: An isolated working session for executing specific tasks

Workspace

Default working directory: ~/clawd

Contains the following important files:

  • SOUL.md: The assistant’s personality and behavioral guidelines
  • USER.md: User information and preferences
  • MEMORY.md: Long-term memory (loaded in main session only)
  • memory/YYYY-MM-DD.md: Daily memory logs
  • TOOLS.md: Environment-specific tool configuration
  • HEARTBEAT.md: Periodic check task list

Skills Mechanism

What Are Skills

Skills are reusable functional modules that provide specific tools and capabilities.

Currently Available Skills

1. bluebubbles

  • Purpose: Send and manage iMessages via BlueBubbles
  • Usage: message tool with channel="bluebubbles"
  • Features: Send messages, reply, edit, react, etc.

2. coding-agent

  • Purpose: Delegate coding tasks to a specialized AI agent
  • Use cases:
    • Creating new features or applications
    • Code review
    • Large codebase refactoring
    • Iterative coding that requires file exploration
  • Not for: Simple one-line edits, reading code (use the read tool), working in ~/clawd
  • Note: Requires a bash tool with pty:true support

3. healthcheck

  • Purpose: Security hardening and risk tolerance configuration for OpenClaw deployments
  • Use cases:
    • Security audits
    • Firewall/SSH/update hardening
    • Risk assessment
    • Periodic security checks for OpenClaw
    • Version status checks

4. skill-creator

  • Purpose: Create or update AgentSkills
  • Use cases:
    • Designing skills
    • Building skill structures
    • Packaging skills with scripts, references, and resources

5. weather

  • Purpose: Get current weather and forecasts via wttr.in or Open-Meteo
  • Use cases: When the user asks about weather, temperature, or forecasts for any location
  • Not for: Historical weather data, severe weather alerts, detailed meteorological analysis
  • Advantage: No API key required

Using Skills

When a skill is clearly applicable, the tool automatically loads its SKILL.md file and follows its instructions.

Session Management

Sub-agents

Used for executing isolated tasks. Can be run as:

  • One-shot run (mode=”run”): Executes a single task then cleans up automatically
  • Persistent session (mode=”session”): Keeps the session alive for multiple interactions

Use cases:

  • Tasks that need an independent context
  • Long-running background tasks
  • Multiple independent tasks running concurrently

Session Communication

  • sessions_send: Send messages to other sessions
  • subagents: Manage sub-agents (list, terminate, bootstrap)

Message Handling

Message Routing

  • Reply in current session: Automatically routed back to the source channel (Signal, Telegram, etc.)
  • Cross-session: Use sessions_send(sessionKey, message)
  • Sub-agent coordination: Use the subagents tool

Message Tool

Operations supported by the message tool:

  • send: Send a message
  • react: Add an emoji reaction
  • edit: Edit a message
  • unsend: Retract a message
  • reply: Reply to a message
  • sendWithEffect: Send a message with an effect
  • sendAttachment: Send an attachment

Platform Formatting

  • Discord/WhatsApp: Don’t use Markdown tables; use bullet points instead
  • Discord links: Use <> to suppress embeds: <https://example.com>
  • WhatsApp: Don’t use headings; use bold or uppercase for emphasis

Tool Usage

File Operations

  • read: Read file contents
  • write: Create or overwrite a file
  • edit: Precisely edit a file

Command Execution

  • exec: Run shell commands (supports pty for CLIs that need a TTY)
  • process: Manage background execution sessions

Network Operations

  • web_search: Search the web using the Brave Search API
  • web_fetch: Fetch and extract readable content from a URL

Browser Control

  • browser: Control the browser via OpenClaw’s browser control server
    • Supported profiles: chrome (Chrome extension relay) or openclaw (isolated browser)
    • Used for UI automation, screenshots, navigation, etc.

Common Commands

Gateway Management

1
2
3
4
5
openclaw gateway status    # Check status
openclaw gateway start     # Start
openclaw gateway stop      # Stop
openclaw gateway restart   # Restart
openclaw help              # View help

Status Check

1
openclaw status            # System status

Scheduled Tasks and Reminders

Cron Jobs

Use cases:

  • Precise time scheduling (“every Monday at 9 AM”)
  • Tasks that need to be isolated from main session history
  • Tasks that need a different model or reasoning level
  • One-off reminders (“remind me in 20 minutes”)
  • Tasks whose output should be delivered directly to a channel

Heartbeats

Use cases:

  • Multiple checks that can be batched together (inbox + calendar + notifications)
  • Conversation context that needs recent messages
  • Timing that can drift slightly (every ~30 minutes is fine, no need to be exact)
  • Reducing API calls by combining periodic checks

Periodic check content (2-4 times per day):

  • Email — Any unread urgent messages?
  • Calendar — Events in the next 24-48 hours?
  • Mentions — Twitter/social notifications?
  • Weather — If the user might be heading out

Tracking check state (memory/heartbeat-state.json):

1
2
3
4
5
6
7
{
  "lastChecks": {
    "email": 1703275200,
    "calendar": 1703260800,
    "weather": null
  }
}

Config File Reference

AGENTS.md

The root of the workspace; defines the bootstrap rules for session startup.

SOUL.md

The assistant’s soul — defines personality, boundaries, and tone.

USER.md

User information, including how to address them, timezone, preferences, etc.

MEMORY.md

Long-term memory, loaded in the main session only. Contains decisions, context, and things to remember.

TOOLS.md

Environment-specific tool notes (camera names, SSH hosts, TTS preferences, etc.).

IDENTITY.md

Assistant identity information (name, bio, emoji, etc.).

Tips and Best Practices

Memory Management

Daily memory (memory/YYYY-MM-DD.md):

  • Raw log of what happened that day
  • Create the memory/ directory if it doesn’t exist

Long-term memory (MEMORY.md):

  • Periodically (every few days) review daily files via heartbeat
  • Identify important events, lessons, or insights worth keeping long-term
  • Update MEMORY.md with distilled learnings
  • Remove outdated information from MEMORY.md that’s no longer relevant

Combining Checks

  • Consolidate similar periodic checks into HEARTBEAT.md rather than creating multiple cron jobs
  • Use cron for precise scheduling and independent tasks

File Operations

  • Priority: Trash > Delete (recovery beats permanent loss)
  • When in doubt, ask first

External Actions

Ask before taking these actions:

  • Sending emails, tweets, or public posts
  • Anything that leaves the local machine
  • Any action you’re uncertain about

Group Chats

  • Don’t share the user’s profile with others
  • In a group, you are a participant — not their voice or proxy
  • Think before speaking

Path Safety

  • When I was deploying, I was constantly worried about my data being exposed. I tried setting a specific path restriction, but it turns out OpenClaw’s fs setting only supports fs: { workspaceOnly: false } — meaning there’s only a workspace-level security policy.

Troubleshooting

Issue: Tool Not Available

Check openclaw status to confirm system state.

Issue: Can’t Find a Feature

  • Check available Skills
  • Read the Skills documentation
  • Check tool permissions

Issue: Session Not Responding

  • Check Gateway status
  • Try restarting: openclaw gateway restart

Issue: Memory Lost

  • Confirm that MEMORY.md and the memory/ directory exist
  • Check file permissions
  • Review recent memory/YYYY-MM-DD.md files

Resources

AI OpenClaw Assistant