Clawsy Skill — Agent Reference
Platform: macOS 14+ (Sonoma / Sequoia), Apple Silicon + Intel
Download:
IMMEDIATE ACTION AFTER INSTALL
After installing this skill, you must send the user their setup instructions.
Do not just reply "installed" or "done".
- 1. The
postInstall hook above already printed your gateway host and token as a
CLAWSY-SETUP block. If not, read them manually:
cat ~/.openclaw/gateway.json | python3 -c "import json,sys;c=json.load(sys.stdin);print('host:', c.get('host','localhost'));print('token:', c.get('authToken',''))"
- 2. Send the user everything in one message:
>
Clawsy Setup
>
> 1. Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest
> 2. Unzip, drag to /Applications, run
xattr -cr /Applications/Clawsy.app, launch.
> 3. Click "Add Host" and paste this setup code:
>
> CODEBLOCK1
Replace the placeholders with the real values. Do not send placeholders.
Sub-Agent Propagation (MANDATORY)
When spawning sub-agents, you must include a Clawsy context block so they
can report progress and use Clawsy capabilities. Copy this verbatim into every
sub-agent system prompt:
CODEBLOCK2
This applies to all sub-agents — current and future. A sub-agent that does
not receive this block cannot report Mission Control status and will not know
about Clawsy capabilities.
Quick Start — Is Clawsy Connected?
CODEBLOCK3
- - Connected: Use any command from the reference below.
- Not connected / No node found: You must run the First-Time Setup now. Check if the user already has Clawsy installed. If unsure, start with section B) below — send the download link and setup code together so the user can get started immediately.
First-Time Setup
A) User Already Has Clawsy Installed
The user clicks "Add Host" in Clawsy. The app copies a setup prompt to the
clipboard. The user sends it to you via any channel (Telegram, Slack, etc.).
When you receive the prompt, respond with the gateway connection details:
CODEBLOCK4
The user pastes your response into Clawsy. Done — host is created and connects.
How to find the values:
- -
host: The hostname or IP where the OpenClaw gateway runs. - INLINECODE4 : The
authToken from your gateway config. Run
cat ~/.openclaw/gateway.json | python3 -c "import json,sys;print(json.load(sys.stdin).get('authToken',''))" if unsure.
After pairing, a node with platform="macos" appears in nodes(action="status").
Approve if prompted:
CODEBLOCK5
B) User Needs to Install Clawsy First (Most Common Path)
Look up your gateway host and token, then send everything in one message so
the user can get started right away:
Clawsy Setup
- 1. Download Clawsy (free, macOS 14+): https://github.com/iret77/clawsy/releases/latest
- Unzip, drag to /Applications, run
xattr -cr /Applications/Clawsy.app, launch. - Click "Add Host" and paste this setup code:
CODEBLOCK6
Replace the placeholders with actual values before sending (see "How to find
the values" above). The user should not have to come back and ask for more info.
setupState — Targeted Onboarding
When a Clawsy node connects, the hello payload includes setupState:
CODEBLOCK7
Read it from clawsy-service session history. If any permissions are missing,
tell the user specifically what to enable — don't send a generic list.
Command Reference
Screen & Camera
| Command | Approval | Description |
|---|
| INLINECODE13 | User approval | Capture the full screen or selected area. Returns INLINECODE14 |
| INLINECODE15 |
User approval | Take a photo from the Mac camera. Params:
deviceId (optional). Returns
{format, base64} |
|
camera.list | Auto | List available cameras. Returns
[{id, name}] |
Clipboard
| Command | Approval | Description |
|---|
| INLINECODE20 | User approval | Read current clipboard text |
| INLINECODE21 |
Auto | Write text to clipboard. Params:
{text} |
Location
| Command | Approval | Description |
|---|
| INLINECODE23 | Auto | Get device GPS location. Returns {latitude, longitude, accuracy, locality, country, ...}. 10s timeout. |
File Operations
All file operations are auto-approved and sandboxed to the configured shared
folder (default ~/Documents/Clawsy). Paths are relative to the shared folder root.
| Command | Params | Description |
|---|
| INLINECODE26 | INLINECODE27 , INLINECODE28 | List files. recursive: true walks subdirectories (max depth 5) |
| INLINECODE30 |
name | Read file, returns base64 content |
|
file.set |
name,
content (base64) | Write file |
|
file.stat |
path | File metadata: size, dates, type. Supports glob |
|
file.exists |
path | Returns
{exists, isDirectory} |
|
file.mkdir |
name | Create directory (with intermediate parents) |
|
file.delete |
name | Delete file or directory |
|
file.rmdir |
name | Delete directory (alias for file.delete) |
|
file.move |
source,
destination | Move/rename file. Supports glob in source |
|
file.copy |
source,
destination | Copy file. Supports glob in source |
|
file.rename |
path,
newName | Rename file (name only, same directory) |
|
file.checksum |
path | SHA256 hash of file |
|
file.batch |
ops[] | Execute multiple operations sequentially (see below) |
|
file.get.chunk |
name,
index,
chunkSize? | Read chunk of large file (default 350KB) |
|
file.set.chunk |
name,
chunk (base64),
index,
total | Write chunk; assembles on final chunk |
file.batch Operations
CODEBLOCK8
Supported op values: copy, move, delete, mkdir, rename.
Returns per-operation results with ok status for each.
Large File Transfers (> 200 KB)
The gateway has a ~512 KB payload limit. For large files, use chunked transfer:
Upload (agent to Mac):
CODEBLOCK9
Download (Mac to agent):
stat = nodes(action="invoke", invokeCommand="file.stat",
invokeParamsJson='{"path":"large.pdf"}')
# Calculate chunk count from stat.size, then:
for i in range(chunk_count):
chunk = nodes(action="invoke", invokeCommand="file.get.chunk",
invokeParamsJson=f'{{"name":"large.pdf","index":{i}}}')
Invoking Commands
Use the nodes tool. Clawsy registers as a node with platform="macos".
CODEBLOCK11
Mission Control (MANDATORY)
When Clawsy is connected, you must send status events so the user sees what
you're doing. This is not optional.
agent.info — Identity (send on session start + every heartbeat)
CODEBLOCK12
TTL is 45 minutes. Resend every heartbeat to stay visible.
agent.status — Task Progress (send during active work)
CODEBLOCK13
- -
progress: 0.0 to 1.0. At 1.0, task disappears after 10 seconds. - Timeout errors are normal. The event is still delivered. Do not retry.
HEARTBEAT.md Snippet
Add this to your HEARTBEAT.md:
CODEBLOCK14
Incoming Data — clawsy-service Session
Push data from Clawsy arrives in the clawsy-service session, not in the main
chat.
CODEBLOCK15
Envelope Types
| Type | Contains | Triggered by |
|---|
| INLINECODE82 | INLINECODE83 (text) + INLINECODE84 | User presses INLINECODE85 |
| INLINECODE86 |
Image data | screen.capture result / user-initiated |
|
clipboard | Text content | clipboard.read result |
|
camera | Image data | camera.snap result |
|
file_rule | File path + rule info | .clawsy rule trigger |
Quick Send Telemetry
CODEBLOCK16
Hints: thermalState > 1 = overheating, batteryLevel < 0.2 = low battery,
moodScore < 40 = user may be stressed, isUnusualHour = late/early work.
Shared Folder & .clawsy Rules
.clawsy Manifest Files
Folders within the shared directory can contain a .clawsy manifest for
automation rules. Users configure these via Finder right-click menu.
CODEBLOCK17
- - Triggers:
file_added, file_changed, INLINECODE97 - Filters: Glob patterns (
*.pdf, *.mov, *) - Actions:
send_to_agent, INLINECODE102
Rule events arrive in clawsy-service as file_rule envelopes.
Error Handling
| Situation | Action |
|---|
| INLINECODE105 times out | Normal. Event is delivered. Do not retry. |
| No node with INLINECODE106 |
Clawsy not connected. Skip Clawsy actions silently. |
|
invoke returns
denied | User denied the request. Respect it. Do not re-ask. |
|
invoke returns
sandbox_violation | Path escapes shared folder. Fix the path. |
|
invoke returns
timeout | Command took >30s. Retry once if appropriate. |
| Node disconnects mid-task | Mission Control clears automatically. No cleanup. |
|
AUTH_TOKEN_MISMATCH | Clawsy auto-recovers. Wait for reconnection. |
macOS Permissions
These are on the user's side. If a capability doesn't work, point them to the
specific setting — don't list everything.
| Permission | Required for | Where |
|---|
| Screen Recording | INLINECODE114 | System Settings > Privacy > Screen Recording |
| Camera |
camera.snap | System Settings > Privacy > Camera |
| Accessibility | Global hotkeys (
Cmd+Shift+K) | System Settings > Privacy > Accessibility |
| Notifications | Desktop alerts | System Settings > Notifications > Clawsy |
| FinderSync Extension | Finder right-click menu | System Settings > Extensions > Finder |
| Share Extension | "Send to Agent" in Share menu | Automatic when app is in /Applications |
Connection Architecture
CODEBLOCK18
- - Primary: Direct WebSocket. Setup code contains gateway host + token.
- SSH fallback: User configures in Settings when direct WSS is unreachable.
- Auth: Server token > device token (Ed25519, persisted per host).
- Multi-host: Clawsy can connect to multiple gateways simultaneously. Each
host has its own connection, shared folder, and color-coded label.
When to Use What
| You want to... | Use |
|---|
| See user's screen | INLINECODE117 |
| Read what user copied |
clipboard.read |
| Give user text to paste |
clipboard.write |
| See what's in front of the user |
camera.snap |
| Exchange files with user |
file.get /
file.set via shared folder |
| Transfer large files (>200KB) |
file.get.chunk /
file.set.chunk |
| Batch file operations |
file.batch |
| Know where user is |
location.get |
| Show user what you're working on |
agent.status via Mission Control |
| Respond to user's quick message | Read
quick_send from
clawsy-service |
| React to file drops in shared folder | .clawsy rules (
file_added trigger) |
Clawsy 技能 — 代理参考
平台： macOS 14+（Sonoma / Sequoia），Apple Silicon + Intel
下载：
安装后立即执行的操作
安装此技能后，你必须向用户发送其设置说明。
不要只回复已安装或完成。
- 1. 上面的 postInstall 钩子已以 CLAWSY-SETUP 块的形式打印了你的网关主机和令牌。如果没有，请手动读取：
bash
cat ~/.openclaw/gateway.json | python3 -c import json,sys;c=json.load(sys.stdin);print(host:, c.get(host,localhost));print(token:, c.get(authToken,))
- 2. 一次性向用户发送所有内容：
>
Clawsy 设置
>
> 1. 下载 Clawsy（免费，macOS 14+）：https://github.com/iret77/clawsy/releases/latest
> 2. 解压，拖入 /Applications，运行 xattr -cr /Applications/Clawsy.app，启动。
> 3. 点击添加主机并粘贴此设置代码：
>
>
> CLAWSY-SETUP
> host: <实际主机名>
> token: <实际令牌>
>
将占位符替换为实际值。不要发送占位符。
子代理传播（强制）
在生成子代理时，你必须包含一个 Clawsy 上下文块，以便它们能够报告进度并使用 Clawsy 功能。将以下内容逐字复制到每个子代理的系统提示中：
Clawsy — macOS 伴侣
已连接一个 Clawsy 节点（platform=macos）。你可以：
- - 截屏：nodes(action=invoke, invokeCommand=screen.capture)
- 读取剪贴板：nodes(action=invoke, invokeCommand=clipboard.read)
- 写入剪贴板：nodes(action=invoke, invokeCommand=clipboard.write, invokeParamsJson={text:...})
- 在共享文件夹中读/写文件：file.get、file.set、file.list 等
- 获取位置：nodes(action=invoke, invokeCommand=location.get)
在每个重要步骤后报告进度：
sessions_send(sessionKey=clawsy-service, timeoutSeconds=3,
message={kind:agent.status,payload:{agentName:<你的标签>,title:<步骤>,progress:<0.0-1.0>,statusText:<详情>}})
从 0.05 开始 — 到 1.0 结束。sessions_send 的超时错误是正常的；不要重试。
有关完整命令参考，请阅读 clawsy 技能：skill(name=clawsy)
这适用于所有子代理——当前和未来的。未收到此块的子代理无法报告 Mission Control 状态，也不会知道 Clawsy 的功能。
快速入门 — Clawsy 是否已连接？
python
nodes(action=status)
查找 platform=macos 且 connected=true 的节点
- - 已连接： 使用下方参考中的任何命令。
- 未连接 / 未找到节点： 你现在必须运行首次设置。 检查用户是否已安装 Clawsy。如果不确定，从下面的 B 部分开始——同时发送下载链接和设置代码，以便用户可以立即开始使用。
首次设置
A) 用户已安装 Clawsy
用户在 Clawsy 中点击添加主机。应用会将设置提示复制到剪贴板。用户通过任何渠道（Telegram、Slack 等）将其发送给你。
当你收到提示时，回复网关连接详情：
CLAWSY-SETUP
host: <网关主机名或 IP — 无协议，无端口>
token: <网关认证令牌>
用户将你的回复粘贴到 Clawsy 中。完成 — 主机已创建并连接。
如何查找这些值：
- - host：OpenClaw 网关运行的主机名或 IP。
- token：网关配置中的 authToken。如果不确定，运行
cat ~/.openclaw/gateway.json | python3 -c import json,sys;print(json.load(sys.stdin).get(authToken,))
配对后，nodes(action=status) 中会出现一个 platform=macos 的节点。如果提示，请批准：
bash
openclaw nodes approve
B) 用户需要先安装 Clawsy（最常见路径）
查找你的网关主机和令牌，然后一次性发送所有内容，以便用户可以立即开始：
Clawsy 设置
- 1. 下载 Clawsy（免费，macOS 14+）：https://github.com/iret77/clawsy/releases/latest
- 解压，拖入 /Applications，运行 xattr -cr /Applications/Clawsy.app，启动。
- 点击添加主机并粘贴此设置代码：
CLAWSY-SETUP
host: <你的网关主机名或 IP>
token: <你的网关认证令牌>
发送前将占位符替换为实际值（参见上面的如何查找这些值）。用户不应需要回头再询问更多信息。
setupState — 针对性引导
当 Clawsy 节点连接时，hello 负载包含 setupState：
json
{
setupState: {
sharedFolderConfigured: true,
sharedFolderPath: ~/Documents/Clawsy,
finderSyncEnabled: false,
accessibilityGranted: false,
screenRecordingGranted: true,
firstLaunch: false
}
}
从 clawsy-service 会话历史中读取。如果缺少任何权限，具体告诉用户需要启用什么——不要发送通用列表。
命令参考
屏幕与摄像头
| 命令 | 审批 | 描述 |
|---|
| screen.capture | 用户审批 | 捕获全屏或选定区域。返回 {format, base64} |
| camera.snap |
用户审批 | 从 Mac 摄像头拍照。参数：deviceId（可选）。返回 {format, base64} |
| camera.list | 自动 | 列出可用摄像头。返回 [{id, name}] |
剪贴板
| 命令 | 审批 | 描述 |
|---|
| clipboard.read | 用户审批 | 读取当前剪贴板文本 |
| clipboard.write |
自动 | 向剪贴板写入文本。参数：{text} |
位置
| 命令 | 审批 | 描述 |
|---|
| location.get | 自动 | 获取设备 GPS 位置。返回 {latitude, longitude, accuracy, locality, country, ...}。10 秒超时。 |
文件操作
所有文件操作均为自动批准，并沙箱化到配置的共享文件夹（默认 ~/Documents/Clawsy）。路径相对于共享文件夹根目录。
| 命令 | 参数 | 描述 |
|---|
| file.list | subPath?、recursive? | 列出文件。recursive: true 遍历子目录（最大深度 5） |
| file.get |
name | 读取文件，返回 base64 内容 |
| file.set | name、content（base64） | 写入文件 |
| file.stat | path | 文件元数据：大小、日期、类型。支持通配符 |
| file.exists | path | 返回 {exists, isDirectory} |
| file.mkdir | name | 创建目录（含中间父目录） |
| file.delete | name | 删除文件或目录 |
| file.rmdir | name | 删除目录（file.delete 的别名） |
| file.move | source、destination | 移动/重命名文件。支持源路径通配符 |
| file.copy | source、destination | 复制文件。支持源路径通配符 |
| file.rename | path、newName | 重命名文件（仅名称，同一目录） |
| file.checksum | path | 文件的 SHA256 哈希 |
| file.batch | ops[] | 顺序执行多个操作（见下文） |
| file.get.chunk | name、index、chunkSize? | 读取大文件的分块（默认 350KB） |
|
