← Back to Skills Marketplace
lovensky1992-wk

Apple Icloud Suite

by lovensky1992-wk · GitHub ↗ · v1.0.0 · MIT-0
cross-platform ⚠ suspicious
351
Downloads
0
Stars
2
Active Installs
8
Versions
Install in OpenClaw
/install apple-icloud-suite
Description
Apple iCloud 全套服务操作:日历、照片、iCloud Drive、设备查找、提醒事项。 Use when: (1) 用户要求查看/创建/修改/删除日历事件或日程, (2) 用户说"帮我看看今天有什么安排"/"加个日程"/"改一下会议时间", (3) 用户要求查找/下载/管理 iCloud 照片, (4...
README (SKILL.md)

Apple iCloud Suite

iCloud 日历、照片、Drive、设备查找的命令行操作。

Step 0: 依赖与认证检查

1. 依赖验证

python3 -c "import pyicloud; print('pyicloud OK')" 2>/dev/null || echo "需安装: pip install pyicloud"
python3 -c "import caldav; print('caldav OK')" 2>/dev/null || echo "需安装: pip install caldav icalendar"

2. Session 缓存检查(优先复用,避免 2FA)

ls ~/.pyicloud/ 2>/dev/null && echo "有缓存 session" || echo "无缓存,需新认证"
  • 有缓存 → 尝试直接连接,通常无需 2FA
  • 无缓存 → 需要首次认证(见下方认证流程)

3. 认证方式(两条路径)

工具 认证方式 密码类型
pyicloud(照片/Drive/设备) 主密码 + 2FA 验证码 Apple ID 主密码
CalDAV(日历) 应用专用密码 appleid.apple.com 生成

🔴 密码安全:从环境变量读取,不硬编码

export ICLOUD_EMAIL="[email protected]"
export ICLOUD_PASSWORD="xxx"  # 或用 keychain

4. pyicloud 认证

from pyicloud import PyiCloudService
import os
os.environ['icloud_china'] = '1'  # 中国大陆用户必须
api = PyiCloudService(os.environ['ICLOUD_EMAIL'], os.environ['ICLOUD_PASSWORD'], china_mainland=True)

if api.requires_2fa:
    # ⚠️ 需要用户参与:在 iPhone 上查看验证码
    code = input("请输入 iPhone 上收到的 6 位验证码: ")
    api.validate_2fa_code(code)

确认点:2FA 需要用户手动输入验证码。提前告知用户准备 iPhone。

Step 1: 需求分类

用户意图 服务 跳转
"今天有什么安排" / "加个日程" 日历 → Step 2,读 references/calendar.md
"下载照片" / "看看相册" 照片 → Step 2,读 references/photos.md
"手机在哪" / "查找设备" 设备查找 → Step 2,读 references/findmy.md
"iCloud 文件" / "下载文档" Drive → Step 2,读 references/drive.md

Step 2: 执行(按需加载详细文档)

根据 Step 1 的分类,读取对应 reference 文件 获取详细操作指令:

服务 Reference 认证工具 主要脚本
📅 日历 references/calendar.md CalDAV scripts/icloud_calendar.py
📷 照片 references/photos.md pyicloud scripts/icloud-photos.py
📱 设备 references/findmy.md pyicloud scripts/icloud_tool.py
💾 Drive references/drive.md pyicloud scripts/icloud_tool.py
🔧 脚本总览 references/scripts.md 所有脚本用法

脚本选择指南

场景 用哪个脚本
设备查找 / Drive 浏览 scripts/icloud_tool.py(通用工具)
照片浏览/下载 scripts/icloud-photos.py(照片专用)
日历操作 scripts/icloud_calendar.py(CalDAV)
提醒事项 scripts/icloud-reminders.py
备忘录(有限) scripts/icloud-notes.py(⚠️ Apple Notes API 有限)

Step 3: 验证与交付

  1. 确认操作成功(文件已下载/事件已创建/设备已定位)
  2. 展示结果给用户
  3. 照片/文件 → 用 MEDIA:\x3Cpath> 发送
  4. 日历事件 → 格式化展示时间/地点/标题

边界条件

情况 处理
2FA 验证码超时 提醒用户重新发送验证码,重试认证
Session 过期 删除 ~/.pyicloud/ 缓存,重新认证
pyicloud 连接失败 检查网络 → 检查 icloud_china 环境变量 → 重试
应用专用密码无效(CalDAV) 引导用户到 appleid.apple.com 重新生成
照片下载量大 >50 张时告知预计时间,分批下载
备忘录需求 Apple Notes 无公开 API,建议用 iCloud.com 网页版
依赖缺失 按 Step 0 安装指引,不继续

注意事项

  • 中国大陆用户:pyicloud 需 china_mainland=True,icloudpd 需 --domain cn
  • 会话缓存:认证成功后 session 保存在 ~/.pyicloud/,通常数周有效
  • 备忘录限制:Apple Notes 没有公开 API,仅有有限的读取能力
Usage Guidance
Before installing or enabling this skill, consider the following: - Metadata mismatch: The skill registry declares no required credentials, but the docs/scripts require Apple ID credentials (main password for pyicloud and/or an app-specific password for CalDAV) and an AMAP API key. Treat that omission as a red flag and ask the publisher to correct it. - Minimize credential exposure: Prefer using an app-specific password for calendar/CalDAV access rather than your Apple ID main password. Do NOT give your primary Apple ID password to untrusted code unless you fully trust the author. If you must test, use a throwaway/test Apple account. - Location and persistence: The status_wall feature runs as a background/daemon process that polls device location frequently and can automatically create/update calendar events. If you enable this, expect continuous location collection and automatic changes to calendars — only enable if you understand and accept the privacy implications. - Verify source and review code: The repository includes multiple Python scripts. If you plan to run them, review status_wall.py and any code that writes ~/.status_wall.json, ~/.status_wall.pid, ~/.status_wall.log or the ~/.pyicloud/ cache to confirm what is stored and where. Running in an isolated environment (VM or throwaway user account) is safer. - Limit autonomous invocation: If the platform allows, disable autonomous invocation for this skill or require explicit user confirmation for operations that collect location or update calendars. Require the skill to not persist credentials in plaintext and to document exactly what is stored and how to revoke it. - Alternative approach: For calendar operations, prefer CalDAV with app-specific passwords; for photos/drive, prefer tools that use OAuth or limited-scope tokens when available. For reverse geocoding, supply your own AMAP key only if you trust the operator, or do geocoding client-side using a service you control. If you want me to produce a short checklist or a suggested minimal permissions/configuration to safely run this skill (e.g., environment variables to set, what to inspect in status_wall.py), I can provide that.
Capability Analysis
Type: OpenClaw Skill Name: apple-icloud-suite Version: 1.0.0 The bundle provides tools for managing iCloud services but includes a 'Status Wall' feature (scripts/status_wall.py) that performs real-time GPS tracking and requires the user's main Apple ID password. The instructions in SKILL.md and references/calendar.md (Scenario 4) direct the AI agent to solicit highly sensitive credentials, including the main Apple ID password and a third-party API key (Amap/高德), to enable background location monitoring. While these capabilities are aligned with the stated 'family collaboration' purpose, the requirement for the primary account password and the implementation of a location-tracking daemon pose significant security and privacy risks. The script communicates with restapi.amap.com for geocoding services.
Capability Tags
requires-sensitive-credentials
Capability Assessment
Purpose & Capability
The name/description (iCloud calendar/photos/Drive/find-my) matches the included scripts and references. However the registry metadata declares no required environment variables or primary credential even though the SKILL.md and scripts clearly require Apple ID credentials (main password and/or app-specific password) and an optional AMAP_API_KEY. The omission of those required secrets in metadata is an incoherence.
Instruction Scope
SKILL.md and the reference files instruct the agent to: collect Apple ID main password (for pyicloud), app-specific password (for CalDAV), 2FA codes, and an AMAP API key; reuse session caches in ~/.pyicloud/; and to run a 'status_wall' background daemon that polls device location and updates shared calendars automatically. These actions go beyond one-shot commands: they collect long-lived credentials, poll/record location, and can autonomously create/update/delete calendar events. That scope is wide and has privacy implications.
Install Mechanism
No download-from-arbitrary-URL installs; dependencies are standard Python packages (pyicloud, caldav, icalendar, icloudpd). The skill comes with Python scripts (bundled) so nothing in the install spec pulls code from unknown hosts. This is proportionate for the claimed functionality.
Credentials
The scripts expect several sensitive environment variables and credentials (ICLOUD_USERNAME/ICLOUD_EMAIL, ICLOUD_PASSWORD — main password, ICLOUD_APP_PASSWORD — app-specific password, ICLOUD_CHINA flag, and AMAP_API_KEY). Requesting an Apple ID main password and a maps API key is reasonable for Find My + reverse geocoding, but the registry metadata lists none of these. Also the codebase alternates names (ICLOUD_EMAIL vs ICLOUD_USERNAME) which is inconsistent. Collecting the Apple ID main password is higher privilege than using app-specific passwords; users should be warned.
Persistence & Privilege
Although always:false, the skill's own documentation and bundled scripts describe a persistent 'status_wall' daemon that polls Find My for GPS every 15 minutes (or 1 minute during commute) and updates shared calendars automatically. Since the agent is allowed autonomous invocation (disable-model-invocation:false by default), this combination gives the skill the ability to collect continual location data and act without frequent user prompts — a notable persistence/privacy risk.
How to Use
  1. Make sure OpenClaw is installed (local or Docker)
  2. Run the install command in chat: /install apple-icloud-suite
  3. After installation, invoke the skill by name or use /apple-icloud-suite
  4. Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Weekly sync
v1.0.7
Daily sync
v1.0.6
Daily sync
v1.0.5
Daily sync
v1.0.4
Daily sync
v1.0.3
Daily sync
v1.0.2
Daily sync
v1.0.1
Initial sync with unique slug
Metadata
Slug apple-icloud-suite
Version 1.0.0
License MIT-0
All-time Installs 2
Active Installs 2
Total Versions 8
Frequently Asked Questions

What is Apple Icloud Suite?

Apple iCloud 全套服务操作:日历、照片、iCloud Drive、设备查找、提醒事项。 Use when: (1) 用户要求查看/创建/修改/删除日历事件或日程, (2) 用户说"帮我看看今天有什么安排"/"加个日程"/"改一下会议时间", (3) 用户要求查找/下载/管理 iCloud 照片, (4... It is an AI Agent Skill for Claude Code / OpenClaw, with 351 downloads so far.

How do I install Apple Icloud Suite?

Run "/install apple-icloud-suite" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Apple Icloud Suite free?

Yes, Apple Icloud Suite is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Apple Icloud Suite support?

Apple Icloud Suite is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Apple Icloud Suite?

It is built and maintained by lovensky1992-wk (@lovensky1992-wk); the current version is v1.0.0.

💬 Comments