nextcloud-aio-oc (NextCloud AIO OpenClaw)

NextCloud AIO OpenClaw Skill

This skill connects OpenClaw to Nextcloud for:

• Notes API
• CalDAV Tasks and Events
• WebDAV Files
• CardDAV Contacts

Primary goal: Predictable, loss-resistant Nextcloud reads/writes.

This skill is validated against:

• Nextcloud Hub 25 Autumn (32.0.6)
• OpenClaw (2026.3.2)

Required Configuration

Set these environment variables:

• NEXTCLOUD_URL (example: https://cloud.example.com)
• NEXTCLOUD_USER
• NEXTCLOUD_TOKEN (App Password strongly preferred)
• NEXTCLOUD_TIMEZONE (recommended, IANA timezone like America/Los_Angeles; used for timezone-less date/time inputs)

Runtime and Metadata Contract

This section is the source of truth for registry metadata parity.

• Required binary: node (Node.js 20+)
• Required environment variables: NEXTCLOUD_URL, NEXTCLOUD_USER, NEXTCLOUD_TOKEN
• Optional environment variable: NEXTCLOUD_TIMEZONE
• Required network target: the host defined by NEXTCLOUD_URL (plus normal redirects from that host)

If a registry entry says "no required binaries" or "no required env vars", treat it as stale metadata and fix before publishing.

Preflight Audit Gate

Before first execution in any new environment:

• Complete the bundled script review checklist below.
• Confirm no unexpected endpoints or privileged system calls are present.
• If checks are incomplete, do not run the skill.
• Prefer sandbox/container validation and least-privilege app credentials first.

Security and Publish Safety

• Never hardcode credentials in SKILL.md, scripts, examples, commit messages, or changelog text.
• Store secrets only in environment variables or local secret stores.
• Use dedicated app passwords for integrations; rotate if leaked or shared.
• Keep local .env files out of git (see .gitignore).
• Before publishing, run a quick scan for obvious secrets and remove any accidental values.

Bundled Script Review Checklist (Before First Use)

The skill ships two scripts: scripts/nextcloud.js (Node.js, text operations) and scripts/files_binary.py (Python 3, binary file transfers). Review both before running in new environments:

1. Confirm runtime requirements:
   • node --version (must be 20+)
2. Check obvious outbound endpoints:
   • rg -n "https?://" scripts/nextcloud.js
3. Check sensitive capability usage:
   • rg -n "child_process|spawn\\(|exec\\(|require\\(\"fs\"\\)|require\\('fs'\\)|fs\\." scripts/nextcloud.js
4. Verify credentials are env-driven only:
   • rg -n "NEXTCLOUD_URL|NEXTCLOUD_USER|NEXTCLOUD_TOKEN|NEXTCLOUD_TIMEZONE" scripts/nextcloud.js
5. Run in low-risk mode first:
   • Use a dedicated low-privilege Nextcloud app password
   • Test against non-production data when possible

If review confidence is low, do not run until code is reviewed by a trusted maintainer.

Static audit snapshot (current bundle)

Quick grep-style checks on scripts/nextcloud.js should currently show:

• Config is read from process.env.NEXTCLOUD_URL|USER|TOKEN|TIMEZONE.
• Request path is built as ${CONFIG.url}${endpoint} and uses fetch(...).
• No obvious child_process or fs usage in the bundle entry path.

Quick checks on scripts/files_binary.py:

• Config is read from os.environ.get("NEXTCLOUD_URL|USER|TOKEN").
• DAV URL is built as {url}/remote.php/dav/files/{user}/{path}.
• Uses only stdlib (urllib, base64, xml.etree); no third-party deps.

This is not a full security audit. Re-run checks after every bundle update.

Run

node scripts/nextcloud.js <command> <subcommand> [options]

Commands

Notes

• notes list
• notes get --id <id>
• notes create --title <title> --content <content> [--category <category>]
• notes edit --id <id> [--title <title>] [--content <content>] [--category <category>]
• notes delete --id <id>

Tasks

• tasks list [--calendar <calendar-name>]
• tasks create --title <title> [--calendar <calendar-name>] [--due <iso>] [--priority <0-9>] [--description <text>] [--timezone <IANA>]
• tasks edit --uid <uid> [--calendar <calendar-name>] [--title <title>] [--due <iso>] [--priority <0-9>] [--description <text>] [--timezone <IANA>]
• tasks delete --uid <uid> [--calendar <calendar-name>]
• tasks complete --uid <uid> [--calendar <calendar-name>]

Calendar Events

• calendar list [--from <iso>] [--to <iso>] (default: next 7 days)
• calendar create --summary <summary> --start <iso-or-date> --end <iso-or-date> [--calendar <calendar-name>] [--description <text>] [--timezone <IANA>] [--all-day]
• calendar edit --uid <uid> [--calendar <calendar-name>] [--summary <summary>] [--start <iso-or-date>] [--end <iso-or-date>] [--description <text>] [--timezone <IANA>] [--all-day]
• calendar delete --uid <uid> [--calendar <calendar-name>]

Important:

• In many setups, Contact birthdays appears as an events calendar but is read-only.
• Birthdays must be managed through contacts create/edit --birthday ..., not through calendar create/edit.
• calendar list returns event summary, start, end, and may include location and description when present.

Calendar Discovery

• calendars list [--type <tasks|events>]

Files (text)

• files list [--path <path>]
• files search --query <query> (supports natural-language input; ranks by filename/path token relevance)
• files get --path <path> (accepts relative user path or full DAV href)
• files upload --path <path> --content <content>
• files delete --path <path>

Files (binary) — ODT, DOCX, PDF, images, etc.

nextcloud.js passes file content as text strings, which corrupts binary formats. Use the companion Python script for any binary file:

python3 scripts/files_binary.py download <nc_path> <local_path>
python3 scripts/files_binary.py upload   <local_path> <nc_path>
python3 scripts/files_binary.py exists   <nc_path>
python3 scripts/files_binary.py list     [<nc_path>]

Reads the same NEXTCLOUD_URL, NEXTCLOUD_USER, NEXTCLOUD_TOKEN env vars. Auto-detects MIME type from file extension (ODT, DOCX, XLSX, PDF, PNG, JPG, and more).

When to use which:

Contacts

• contacts list [--addressbook <name>]
• contacts get --uid <uid> [--addressbook <name>]
• contacts search --query <query> [--addressbook <name>]
• contacts create [--name <full-name>] [--first-name <given>] [--last-name <family>] [--middle-name <middle>] [--prefix <prefix>] [--suffix <suffix>] [--addressbook <name>] [--email <single>] [--emails <csv>] [--phone <single>] [--phones <csv>] [--organization <org>] [--title <title>] [--note <note>] [--birthday <YYYY-MM-DD|YYYYMMDD|--MM-DD|--MMDD>]
• contacts edit --uid <uid> [--addressbook <name>] [--name <full-name>] [--first-name <given>] [--last-name <family>] [--middle-name <middle>] [--prefix <prefix>] [--suffix <suffix>] [--email <single>] [--emails <csv>] [--phone <single>] [--phones <csv>] [--organization <org>] [--title <title>] [--note <note>] [--birthday <YYYY-MM-DD|YYYYMMDD|--MM-DD|--MMDD>]
• contacts delete --uid <uid> [--addressbook <name>]

Address Book Discovery

• addressbooks list

Contact Data Contract (Important)

Use fullName and structuredName as canonical name fields.

Contact output includes:

• uid
• addressBook
• fullName
• structuredName with:
  • familyName
  • givenName
  • additionalNames
  • honorificPrefixes
  • honorificSuffixes
• nameRaw (raw N value for diagnostics only; do not display to users by default)
• emails array or null
• phones array or null
• organization, title, note
• birthday normalized for readability (YYYY-MM-DD or --MM-DD when possible)
• birthdayRaw (raw CardDAV value)

Reliability Rules (Quick Reference)

Apply these on every write to prevent corruption and confusion:

1. Identity and naming

• Never infer UID from URL; always use payload uid.
• Use fullName and structuredName for user-facing names; keep nameRaw diagnostic-only.

2. Contact and birthday integrity

• Birthday input formats: YYYY-MM-DD, YYYYMMDD, --MM-DD, --MMDD.
• Never add trailing semicolons to BDAY.
• Birthdays are contact fields: use contacts create/edit --birthday ...; never edit birthday-derived calendar entries directly.

3. Intent-preserving updates

• Modify only fields explicitly requested by the user.
• To clear a value, pass explicit empty values.
• Respect explicit --addressbook; otherwise use remembered default or ask once.

4. Calendar and task validation

• Validate date/datetime inputs before sending; require end > start for timed events.
• Escape ICS text fields (SUMMARY, DESCRIPTION).
• Validate task priority range (0..9).
• For timezone-less timed input, use --timezone or NEXTCLOUD_TIMEZONE.
• For all-day events, use VALUE=DATE semantics with exclusive DTEND.

5. Capability and safety checks

• Do not assume listed event calendars are writable.
• Treat Contact birthdays as read-only/system calendar.
• If no writable event calendar exists, explain event mutation is unavailable until writable access exists.
• Some calendars are multi-component (VEVENT + VTODO); keep them eligible for both event/task flows.

6. Files and post-write verification

• Require non-empty file paths for files upload/get/delete.
• Escape XML filter/search values for CardDAV/WebDAV operations.
• After mutations (create, edit, complete, delete), verify with follow-up read/list when practical.
• For propagation delay, retry around 0.5s, 1s, 2s before declaring failure.

Known Nextcloud/CardDAV Behaviors

• Servers/clients may negotiate or normalize vCard versions (3.0 vs 4.0) and content on write/read.
• FN and N should each appear once in valid contacts.
• BDAY failures are often malformed input (for example stray delimiters), not server instability.
• Folded vCard lines must be unfolded before parsing.

Error to Action Map (Fast)

• HTTP 403 on calendar create/edit/delete -> likely read-only/system calendar or missing permission; switch to writable events calendar.
• HTTP 501 on files search -> WebDAV SEARCH unsupported; fallback to recursive PROPFIND + client-side filter.
• HTTP 415 on task/event update -> malformed ICS payload; normalize formatting and retry once.
• Contact write succeeded but UI still stale -> run verification retry cycle before reporting failure.

Agent Behavior: Default Calendar Selection

When user creates tasks/events without explicit calendar:

1. Run calendars list --type tasks or calendars list --type events.
2. For events, filter out likely read-only calendars first (Contact birthdays, Holidays, names containing read only or readonly).
3. If at least one writable calendar remains, ask for selection.
4. Ask whether to remember as default.
5. Store in memory.
6. If no writable events calendar remains, explain why event mutation is unavailable and suggest creating a writable calendar in Nextcloud Calendar.

Memory keys:

• default_task_calendar
• default_event_calendar

Agent Behavior: Default Address Book Selection

When user creates contacts without explicit address book:

1. Run addressbooks list.
2. Ask for selection.
3. Ask whether to remember default.
4. Store in memory.

Memory key:

• default_addressbook

Agent Behavior Playbooks (Condensed)

These playbooks are execution shortcuts. Reliability and safety rules above still apply.

Contacts and Birthdays

1. Resolve address book (--addressbook or remembered default).
2. For create/edit, pass only user-requested fields; use explicit empty values when user wants fields cleared.
3. Use --name for full-name input; use structured-name flags for split-name input.
4. Pass multiple emails/phones as CSV values.
5. Birthday changes always go through contacts (contacts create/edit --birthday ...), never calendar mutation commands.
6. Verify birthday/name-sensitive writes with contacts get --uid ... when confidence is important.

Tasks

1. Resolve task calendar when omitted.
2. Validate due and priority (0..9) before write.
3. After create/edit/complete/delete, verify via focused list/get when practical.

Calendar Events

1. Resolve writable events calendar; treat Contact birthdays and system calendars as read-only.
2. Validate start/end and require end > start for timed events.
3. For timezone-less date-times, pass --timezone or use NEXTCLOUD_TIMEZONE.
4. For all-day intent, use --all-day with date values (not timed midnight ranges).
5. Re-list in a focused window after mutation when confidence is important.

All-day end-date normalization behavior:

• start=YYYY-MM-DD, end=YYYY-MM-DD -> inclusive single-day input, normalized.
• start=YYYY-MM-DD, end=next-day -> already-exclusive single-day input.
• Multi-day inclusive ranges -> normalized to canonical exclusive DTEND.

Appointment briefing workflow (high priority intent)

Use this when user asks for appointment details, address, or "what is my appointment today":

1. Determine "today" in NEXTCLOUD_TIMEZONE (or ask if timezone is unclear).
2. Run calendar list --from <start-of-day-iso> --to <end-of-day-iso>.
3. Filter events by user terms (for example dermatology, doctor, provider name).
4. For the selected event, include summary, time window, location, and key lines from description.
5. If multiple events match, ask a quick disambiguation question.
6. If none match, clearly say none found for today and offer to check tomorrow or full week.
7. Provide a plain-text message suitable for SMS/chat (short lines, no markdown).

Files

1. Require explicit file path for mutating operations.
2. files get/upload/delete accept either a relative user path (for example /Share-Family/file.docx) or a full DAV href returned by search.
3. For binary files (ODT, DOCX, PDF, images), use python3 scripts/files_binary.py — never pass binary content through nextcloud.js files upload.
4. Use deterministic test paths for temporary validation files.
5. Read back uploaded content and then delete test files.
6. Use files search with user phrasing directly; it auto-normalizes query text and ranks likely matches.
7. On large instances, prefer narrower path-based listing before broad search to reduce load.

Notes

1. Create with explicit title/content.
2. Read back by id after create/edit.
3. Delete temporary test notes after verification.

Internal Smoke Test Protocol

When validating this skill in a live environment:

1. Contacts: create -> get -> edit -> get -> optional delete.
2. Notes: create -> get -> edit -> get -> delete.
3. Files: upload -> get -> search/list -> delete.
4. Tasks: create -> list/locate -> edit -> complete -> delete.
5. Calendar: create -> list/locate -> edit -> delete.

Use a unique timestamped suffix on all test data and clean up all temporary artifacts unless the user requests keeping them. Use least-privilege credentials for tests and monitor outbound traffic; the process should only communicate with NEXTCLOUD_URL.

Calendar exception handling:

• If no writable event calendar exists, mark calendar mutation tests as intentionally skipped (environment limitation), and still run calendar list.
• Do not treat this as a skill failure; treat it as a server capability/permission constraint.

Persistent Rules (Store These)

Persist these high-value rules in memory/rules:

1. Birthdays are contact fields: use contacts create/edit --birthday ...; never mutate Contact birthdays directly.
2. For all-day events, always use calendar create/edit --all-day with date values (avoid timed midnight ranges).
3. For timezone-less timed values, use --timezone or NEXTCLOUD_TIMEZONE; ask if timezone is unknown.
4. Prefer writable user calendars for event mutations; if 403, report likely read-only/permission issue.
5. Verify event/contact writes with a focused read/list before declaring final success.
6. Keep canonical all-day encoding (VALUE=DATE); avoid duplicate compatibility events unless explicitly requested.

Troubleshooting Playbook

• Birthday was updated but not visible in Nextcloud UI yet:

  • Run contacts get --uid ... immediately.
  • If value is correct in API, advise short wait + UI refresh.
  • Re-check after retry intervals before escalating.

• contacts get and contacts search disagree briefly:

  • Prefer retry cycle and then trust latest consistent result.
  • Do not create duplicate contact entries while waiting.

• Event creation keeps failing:

  • Run calendars list --type events and verify at least one writable non-system calendar exists.
  • If only birthday/system calendars exist, explain limitation and stop mutation attempts.

Output Envelope

All commands return JSON:

Success:

{
  "status": "success",
  "data": {}
}

Error:

{
  "status": "error",
  "message": "Error description"
}