iCloud

Let agents operate your iCloud Drive, Photos, and Find My safely with local 2FA authentication and explicit confirmation gates.

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install icloud

Setup

On first use, read setup.md for secure integration guidelines.

When to Use

Use this skill when the user wants agents to interact with their own iCloud account: list devices, retrieve Find My status, inspect iCloud Drive, or pull photo metadata/files. Use it for operational automation with strict safety gates, not for bypassing Apple account security.

Architecture

Memory lives in ~/icloud/. See memory-template.md for structure and status fields.

~/icloud/
|-- memory.md               # Status, integration mode, and current account scope
|-- operations-log.md       # Executed commands, result checks, and rollback notes
|-- device-map.md           # Known device aliases and stable IDs
|-- drive-map.md            # iCloud Drive folder map and verified paths
`-- safety-events.md        # Confirmed risky actions and explicit approvals

Quick Reference

Load only the file needed for the current task.

Topic	File
Setup flow	`setup.md`
Memory template	`memory-template.md`
Authentication and session handling	`auth-session.md`
Find My operations	`findmy-ops.md`
iCloud Drive operations	`drive-ops.md`
Photos operations	`photos-ops.md`
Safety boundaries and confirmations	`safety-boundaries.md`

Core Rules

1. Authenticate Locally, Never Through Chat

Never ask the user to paste Apple password, 2FA code, session token, or app password in conversation.
Use interactive local auth with terminal prompts or secure local input prompts only.

2. Start Read-Only, Then Escalate

Run read-only discovery first: account reachability, device list, folder listing, metadata checks.
Do not run write operations until read checks pass and scope is explicit.

3. Require Explicit Confirmation for Risky Actions

Treat lost mode, message push, file rename/delete, and bulk upload as risky.
Before running risky actions, summarize target, effect, and rollback option, then request explicit confirmation.

4. Use Deterministic Verification After Every Action

After each operation, verify expected state with a second read call.
Never report success from command exit code alone.

5. Keep Operations Narrow and Idempotent

Operate on one device ID or one file path per step when possible.
Prefer repeat-safe commands and avoid broad wildcard operations.

6. Handle 2FA and Session Expiry as Normal State

If Apple invalidates the session, pause destructive operations and re-auth first.
Continue only after session trust is restored and read checks succeed again.

7. Persist Only Minimal Operational Context

Store only what improves reliability (IDs, verified paths, successful patterns).
Never persist secrets or raw credential material in local memory files.

Common Traps

Asking for Apple credentials in chat -> immediate privacy and trust failure.
Running write operations before discovery -> wrong device/path targeted.
Using device names without IDs -> ambiguous actions on similarly named devices.
Assuming session validity across days -> sudden auth failures mid-workflow.
Executing bulk file changes without snapshot -> difficult rollback after mistakes.
Claiming action success without re-read verification -> silent failures reach users.

External Endpoints

Endpoint	Data Sent	Purpose
https://idmsa.apple.com	Apple account auth payload during login	Apple ID authentication
https://setup.icloud.com	Session and webservice negotiation	iCloud service bootstrap
https://www.icloud.com	Service API requests (Drive/Photos/Find My)	iCloud operations
https://idmsa.apple.com.cn	Apple account auth payload (China mainland accounts)	Regional Apple ID authentication
https://setup.icloud.com.cn	Session and webservice negotiation (China mainland accounts)	Regional iCloud bootstrap
https://pypi.org	Package metadata (install time only)	Install `pyicloud`
https://files.pythonhosted.org	Package download (install time only)	Install `pyicloud`

No other data is sent externally by this skill's documented workflow.

Security & Privacy

Data that leaves your machine:

Apple account authentication and iCloud API requests needed for requested operations.
Package install traffic only when installing dependencies.

Data that stays local:

Optional operational notes under ~/icloud/.
Local keyring entries managed by the pyicloud tool if the user chooses to store password.

This skill does NOT:

Bypass Apple security flows or 2FA requirements.
Request undeclared credentials in chat.
Execute undeclared network endpoints.
Modify its own SKILL file.

Trust

By using this skill, you trust Apple iCloud endpoints and the pyicloud package. Only install and run this workflow if you trust these services with your account operations.

Related Skills

Install with clawhub install <slug> if user confirms:

cloud-storage - Cross-provider storage workflows and transfer safety checks
ios - Apple device settings, permissions, and account behavior troubleshooting
macos - macOS security, keychain, and runtime diagnostics for Apple tooling
photos - Media management strategies when iCloud Photos is the main workload

Feedback

If useful: clawhub star icloud
Stay updated: clawhub sync