openclaw/docs/reference/AGENTS.default.md at codex/matrix-qa-29

mirror of https://github.com/openclaw/openclaw.git synced 2026-08-25 11:55:47 -06:00

Files

T

Peter Steinberger 554fb212c9 fix(nodes): report camera positions the hardware actually reached (#128595 )

* fix(nodes): report camera positions the hardware actually reached

`camera.ptz.control` returned a position it never verified, and
`camera.snap`/`camera.clip` could capture from a camera the caller did
not ask for. Both told the agent an action succeeded when it had not.

PTZ read its post-write status from the same UVC connection that issued
the write. Gimbal cameras echo a pending setpoint back on the writing
connection, so the check confirmed its own write. Those cameras also
service camera-terminal controls only while a video stream is active, and
no capture session was held, so writes could be discarded entirely while
reads returned phantom values.

Hold a frame-discarding capture session across every PTZ operation, close
the writing controller, and verify through a fresh connection against each
axis's advertised resolution. An axis that misses now reports through the
existing CAMERA_PTZ_PARTIAL outcome with observed versus requested values
and what to check next.

Apple camera selection accepted an explicit deviceId and silently fell
back to the default camera when nothing matched. Linux already rejected
this, and CameraPTZService already rejected it in the same app. Centralize
exact selection in OpenClawKit so macOS and iOS both fail with a
device-not-found error; the facing/default fallback stays only for
requests that supply no deviceId.

camera.ptz.status now activates the camera and its privacy indicator for
the duration of the read. That is the cost of returning real positions.

* fix(nodes): tell callers how to recover from an unknown camera ID

Device IDs change when cameras are reconnected, so a bare
device-not-found error dead-ends the caller. Both Apple errors and the
docs now point at camera.list for current IDs.

Addresses the ClawSweeper P2 finding on #128595.

2026-08-24 01:56:12 -07:00

6.9 KiB

Raw Permalink Blame History

summary, title, read_when

summary

title

read_when

Default OpenClaw agent instructions and skills roster for the personal assistant setup

Default AGENTS.md

Starting a new OpenClaw agent session

Enabling or auditing default skills

First run (recommended)

OpenClaw agents use a workspace directory. Default: ~/.openclaw/workspace (configurable via agents.defaults.workspace, supports ~).

Create the workspace:

mkdir -p ~/.openclaw/workspace

Copy the default workspace templates into it:

cp docs/reference/templates/AGENTS.md ~/.openclaw/workspace/AGENTS.md
cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md

Optional: use this file's personal-assistant skill roster instead of the generic template:

cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md

Optional: point at a different workspace:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Safety defaults

Don't dump directories or secrets into chat.
Don't run destructive commands unless explicitly asked.
Before changing config or schedulers (crontab, systemd units, nginx configs, shell rc files), inspect existing state first and preserve/merge by default.
Don't send partial/streaming replies to external messaging surfaces (only final replies).

Existing solutions preflight

Before proposing or building a custom system, feature, workflow, tool, integration, or automation, check for open-source projects, maintained libraries, existing OpenClaw plugins, or free platforms that already solve it well enough. Prefer those when adequate. Build custom only when existing options are unsuitable, too expensive, unmaintained, unsafe, non-compliant, or the user explicitly asks for custom. Avoid paid-service recommendations unless the user explicitly approves spend. Keep this lightweight, a preflight gate, not a research assignment.

Session start (required)

Read SOUL.md, USER.md, and today+yesterday in memory/ before responding.
Read MEMORY.md when present.

Soul (required)

SOUL.md defines identity, tone, and boundaries. Keep it current.
If you change SOUL.md, tell the user.
You are a fresh instance each session; continuity lives in these files.

Shared spaces (recommended)

You're not the user's voice; be careful in group chats or public channels.
Don't share private data, contact info, or internal notes.

Memory system (recommended)

Daily log: memory/YYYY-MM-DD.md (create memory/ if needed).
User model: USER.md for dated active or superseded directives about stable preferences and profile facts.
Long-term memory: MEMORY.md for durable non-profile facts and decisions.
Lowercase memory.md is legacy repair input only; do not keep both root files on purpose.
On session start, read today + yesterday + MEMORY.md when present.
Before writing memory files, read them first; write only concrete updates, never empty placeholders.
Capture preferences as directives in USER.md; capture decisions, constraints, and open loops in durable or daily memory as appropriate.
Avoid secrets unless explicitly requested.

Tools

Local notes

Tools live in skills; follow each skill's SKILL.md when you need it.
Keep environment-specific notes in this file's ## Tools section.

Backup tip (recommended)

Treat this workspace as the assistant's memory: make it a git repo (ideally private) so AGENTS.md and memory files are backed up.

cd ~/.openclaw/workspace
git init
git add AGENTS.md
git commit -m "Add workspace"
# Optional: add a private remote + push

What OpenClaw does

Runs a messaging-channel gateway (WhatsApp, Telegram, Discord, Signal, iMessage, Slack, and more) plus an embedded agent, so the assistant can read/write chats, fetch context, and run skills via the host machine.
The macOS app manages permissions (screen recording, notifications, microphone) and exposes the openclaw CLI via its bundled binary.
Direct chats collapse into the agent's main session by default; groups and channels/rooms get their own session keys. See Channel routing for the exact key formats. Heartbeats keep background tasks alive.

Core skills (enable in Settings → Skills)

Example roster for a personal-assistant workspace; swap in whichever skills fit your setup.

mcporter - tool server runtime/CLI for managing external skill backends.
Peekaboo - fast macOS screenshots with optional AI vision analysis.
camsnap - capture frames, clips, or motion alerts from RTSP/ONVIF security cams and local webcams, including USB pan/tilt/zoom control.
oracle - OpenAI-ready agent CLI with session replay and browser control.
eightctl - control your sleep, from the terminal.
imsg - send, read, stream iMessage & SMS.
wacli - WhatsApp CLI: sync, search, send.
discord - Discord actions: react, stickers, polls. Use user:<id> or channel:<id> targets (bare numeric ids are ambiguous).
gog - Google Suite CLI: Gmail, Calendar, Drive, Contacts.
spotify-player - terminal Spotify client to search/queue/control playback.
sag - ElevenLabs speech with mac-style say UX; streams to speakers by default.
Sonos CLI - control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
blucli - play, group, and automate BluOS players from scripts.
OpenHue CLI - Philips Hue lighting control for scenes and automations.
OpenAI Whisper - local speech-to-text for quick dictation and voicemail transcripts.
Gemini CLI - Google Gemini models from the terminal for fast Q&A.
agent-tools - utility toolkit for automations and helper scripts.

Usage notes

Prefer the openclaw CLI for scripting; the desktop app handles permissions.
Run installs from the Skills tab; the install button is hidden once a required binary is already present.
Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
For browser-driven verification, use the openclaw browser CLI (bundled browser plugin) with the OpenClaw-managed Chrome/Brave/Edge/Chromium profile.
Manage: status, doctor [--deep], start [--headless], stop, tabs, tab [new|select|close], open <url>, focus <id>, close <id>.
Inspect: screenshot [--full-page|--ref|--labels], snapshot [--format ai|aria|--interactive|--efficient], console, errors, requests, pdf, responsebody.
Act: navigate, click <ref>, type <ref> <text>, press, hover, drag, select, upload, download, fill, dialog, wait, evaluate --fn <js>, highlight. Actions need a ref from snapshot (CSS selectors are not accepted for actions); use evaluate when you need document.querySelector-style targeting.
Add --json for machine-readable output on any inspection command.

6.9 KiB Raw Permalink Blame History