# OpenClaw with Apple — 保姆级安装配置教程

> 让 AI 接管你的 iPhone：日历、提醒事项、备忘录、健康分析，全部自动化。

---

## 📖 这是什么？

**OpenClaw with Apple** 是一个 AI Skill（技能包），安装到支持 Skill 的 AI 助手后，AI 就能：

- 📅 **读写你的 iCloud 日历**（创建/查看/删除事件）
- 📋 **自动记录待办到 iPhone 提醒事项**（你说"明天开会"，AI 自动帮你记）
- 📝 **自动记录笔记到 iPhone 备忘录**（你说"记一下 xxx"，AI 自动帮你存）
- 🏥 **深度分析 Apple Health 数据**（心率、睡眠、运动，给你打分+判定）
- 📸 **浏览 iCloud 照片**
- 📁 **管理 iCloud Drive 文件**
- 📍 **查找你的 Apple 设备**（Find My）

**一句话总结**：你只管跟 AI 聊天，它会自动把该记的东西同步到你 iPhone 上。

---

## 🔧 你需要准备什么

| 必需项 | 说明 |
|--------|------|
| **iPhone** | 需要安装「快捷指令」App（系统自带） |
| **Apple ID** | 就是你登录 iCloud 的账号 |
| **支持 Skill 的 AI 助手** | 比如 CodeBuddy、Cursor 等支持加载 SKILL.md 的工具 |
| **macOS 或 Linux 电脑** | 运行 Python 脚本的服务端 |
| **Python 3.8+** | 电脑上需要有 Python 环境 |

---

## 🚀 安装步骤

### 第 1 步：下载项目

```bash
git clone https://github.com/rtjowo/openclaw-with-Apple.git
cd openclaw-with-Apple
```

### 第 2 步：安装 Python 依赖

```bash
pip install pyicloud caldav icalendar
```

> 只有这 3 个依赖，没有其他的。

### 第 3 步：把 Skill 加载到你的 AI 助手

不同的 AI 助手加载方式不同：

- **CodeBuddy**：把项目文件夹作为工作目录打开，AI 会自动识别 `SKILL.md`
- **Cursor**：同上，打开项目文件夹即可
- **其他支持 Skill 的工具**：参考对应工具的文档，加载 `SKILL.md` 文件

加载成功后，AI 会自动引导你完成后续配置。

---

## 🔐 配置 iCloud 登录

AI 加载 Skill 后会主动问你要凭证。你需要准备两样东西：

### 应用专用密码 — 用于日历

> ⚠️ 应用专用密码**只能操控日历**，无法连接提醒事项、备忘录和健康分析。

1. 打开 https://appleid.apple.com
2. 登录你的 Apple ID
3. 找到「登录与安全」→「应用专用密码」
4. 点击「生成应用专用密码」
5. 输入一个标签名（比如 "OpenClaw"）
6. 复制生成的密码（格式类似 `xxxx-xxxx-xxxx-xxxx`）

把这个密码发给 AI 就行。

### Apple ID 邮箱 + 主密码 — 用于提醒事项/备忘录/健康/照片/Drive/设备

> 💡 如果你需要用**提醒事项同步、备忘录同步、健康分析**功能，必须提供 Apple ID 邮箱和主密码。

把你登录 Apple ID 的邮箱和密码告诉 AI 即可。

> **安全说明**：密码只存在本地环境变量中，不会上传到任何地方。登录成功后 session 缓存在 `~/.pyicloud/`，后续不再需要密码。

### 双重认证（2FA）

如果你开了双重认证（大部分人都开了），AI 登录时你的 iPhone 会弹出一个 6 位验证码，把验证码发给 AI 就行。

---

## 📱 配置 iPhone 端（三个功能，按需选择）

> ⚠️ 以下所有 iCloud 链接**必须用 iPhone 的 Safari 浏览器打开**，电脑上打不开！

---

### 🏥 功能一：Apple Health 健康分析

**效果**：每天自动分析你的心率、睡眠、运动数据，生成健康评分和深度报告。

#### 第 1 步：导入快捷指令

用 iPhone Safari 打开：

```
https://www.icloud.com/shortcuts/94862224a4b64ca0bf037b89c8f81cb7
```

点击「添加快捷指令」。

#### 第 2 步：授权健康数据

1. 打开 iPhone「快捷指令」App
2. 找到刚导入的「**Health Daily Export**」
3. 点右上角 `···` 进入编辑模式
4. 系统会弹出多个授权弹窗（步数、心率、睡眠、活动能量、步行距离），**全部点「允许」**
5. 点左上角「完成」退出

> 💡 如果没弹窗：去「设置」→「隐私与安全性」→「健康」→「快捷指令」→ 手动开启所有数据类型。

#### 第 3 步：开启共享大量数据

iPhone →「设置」→「快捷指令」→「高级」→ 开启「**允许共享大量数据**」

> ⚠️ 这一步非常重要！不开会报 "XPC error" 错误。

#### 第 4 步：设置自动化

1. 打开「快捷指令」App → 底部点「自动化」
2. 右上角 `+` →「特定时间」
3. 设置为 **每天 22:00**
4. 选择运行「Health Daily Export」
5. **关闭「运行前询问」**

设置完成后，每晚 22:00 iPhone 会自动采集当天健康数据。

#### 第 5 步：告诉 AI 你配置好了

回到 AI 对话，说"Health 配置好了"，AI 会在服务端设置定时任务，每晚 22:30 自动拉取数据并生成报告。

---

### 📋 功能二：提醒事项同步

**效果**：你跟 AI 聊天时说到要做的事，AI 自动记录，每晚同步到 iPhone「提醒事项」App。

#### 第 1 步：导入快捷指令

用 iPhone Safari 打开：

```
https://www.icloud.com/shortcuts/de68c5443f054355bdb332f246c24a94
```

点击「添加快捷指令」。导入后**手动运行一次**（会创建必要的文件夹）。

#### 第 2 步：设置自动化

1. 打开「快捷指令」App → 底部点「自动化」
2. 右上角 `+` →「特定时间」
3. 设置为 **每天 22:15**
4. 选择运行「Tasks Import」
5. **关闭「运行前询问」**

然后去「设置」→「快捷指令」→「高级」→ 开启「**允许共享大量数据**」

#### 工作流程

```
你对 AI 说"明天去洗车"
        ↓
AI 自动执行命令，写入 tasks_latest.json
        ↓
每晚 21:00 服务端自动推送到 iCloud Drive
        ↓
每晚 22:15 iPhone 自动运行快捷指令
        ↓
「提醒事项」App 里出现"洗车"✓
```

---

### 📝 功能三：备忘录同步

**效果**：你跟 AI 说的笔记、想法、灵感，自动同步到 iPhone「备忘录」App。

#### 第 1 步：导入快捷指令

用 iPhone Safari 打开：

```
https://www.icloud.com/shortcuts/2229591d96a849a6ad9b4e44b4b6ce80
```

点击「添加快捷指令」。导入后**手动运行一次**。

#### 第 2 步：设置自动化

1. 打开「快捷指令」App → 底部点「自动化」
2. 右上角 `+` →「特定时间」
3. 设置为 **每天 22:15**
4. 选择运行「Notes Import」
5. **关闭「运行前询问」**

然后确认「设置」→「快捷指令」→「高级」→「**允许共享大量数据**」已开启。

---

### 📅 功能四：iCloud 日历

**效果**：AI 帮你创建、查看、搜索、删除日历事件，直接同步到 iPhone 日历 App。

> 💡 日历功能不需要快捷指令，只需要前面配置的**应用专用密码**就能用。

#### 它怎么工作

当你跟 AI 说了一件**带具体时间**的事情，AI 会自动写入日历：

| 你说的话 | AI 做什么 |
|---------|----------|
| "明天下午2点开会" | ✅ 写入日历（14:00-15:00） + 写入提醒事项 |
| "周六下午3点到5点打羽毛球" | ✅ 写入日历（15:00-17:00） + 写入提醒事项 |
| "明天去洗车" | ❌ 不写日历（没说几点），只写提醒事项 |

#### 你也可以直接操作日历

| 你说的话 | AI 做什么 |
|---------|----------|
| "看看我今天的日历" | 显示今日所有事件 |
| "这周有什么安排" | 显示本周日历 |
| "帮我建个日程，周六15:00-17:00 打羽毛球" | 创建日历事件 |
| "删掉打羽毛球那个日程" | 搜索并删除 |
| "搜一下最近有没有开会的日程" | 搜索包含"开会"的事件 |

#### 多日历支持

如果你 iCloud 里有多个日历（比如"工作"、"个人"、"家庭看板"），可以指定写到哪个：

```
"帮我在家庭看板日历里加个日程，周日10点带孩子去公园"
```

AI 会用 `--calendar 家庭看板` 参数写到对应日历。

---

## ✅ 配置完成！

配置好后的完整时间线：

| 时间 | 发生什么 |
|------|---------|
| **全天** | 你跟 AI 正常聊天，AI 自动识别待办和笔记并写入文件 |
| **21:00** | 服务端自动把待办/备忘录 JSON 推送到 iCloud Drive |
| **22:00** | iPhone 自动采集当天健康数据 |
| **22:15** | iPhone 自动导入待办到「提醒事项」、笔记到「备忘录」 |
| **22:30** | 服务端自动分析健康数据，生成报告 |

---

## 💬 日常使用方法

配置好之后，你只需要正常跟 AI 聊天就行。以下是一些例子：

### 待办 & 日历

| 你说的话 | AI 会做什么 |
|---------|-----------|
| "明天去洗车" | 写入提醒事项（不写日历，因为没说几点） |
| "明天下午2点开会" | 写入提醒事项 + 写入日历（有具体时间） |
| "后天取快递" | 写入提醒事项 |
| "下周三面试，早上10点" | 写入提醒事项 + 写入日历 |

### 备忘录

| 你说的话 | AI 会做什么 |
|---------|-----------|
| "记一下：React useEffect 空数组只执行一次" | 写入备忘录 |
| "今天学到个东西：Python 的 walrus 运算符" | 写入备忘录 |
| "会议纪要：决定用 React 重构前端" | 写入备忘录 |

### 健康分析

| 你说的话 | AI 会做什么 |
|---------|-----------|
| "分析一下我今天的健康数据" | 运行分析，输出完整报告 |
| "我最近睡眠怎么样" | 分析最近数据，重点看睡眠指标 |
| "看看过去一周的健康趋势" | 生成 7 天趋势报告 |

### iCloud 操作

| 你说的话 | AI 会做什么 |
|---------|-----------|
| "看看我今天的日历" | 显示今日日历事件 |
| "我最近拍了什么照片" | 列出最近照片 |
| "我的 iPhone 在哪" | 定位你的 iPhone |
| "看看 iCloud Drive 里有什么" | 列出 iCloud Drive 文件 |

---

## 🏥 健康报告长什么样

运行 `health_tool.py today` 后，你会看到类似这样的报告：

```
============================================================
  健康深度分析  2026-03-12
============================================================

📊 基础指标
   步数:     7152
   活动能量:  300.0 kcal

❤️ 心率详细（共 486 次测量）
   平均: 71  最高: 120  最低: 50  极差: 70
   夜间静息(精): 53 bpm
   HRV (RMSSD≈): 7.9

😴 睡眠详细
   入睡: 03:02  醒来: 09:40
   实际睡眠: 5.7h
   深度睡眠: 14.3%
   夜间醒来: 5 次

────────────────────────────────────────────────────────────
  💡 深度分析
────────────────────────────────────────────────────────────

  🏃 运动与代谢
    · 今日 7152 步，达到活跃水平

  ❤️ 心血管与自主神经
    · 夜间静息心率在健康范围内，心血管基础状态良好。
    · HRV 偏低，交感神经主导，身体恢复状态较差。

  😴 睡眠深度分析
    · 实际睡眠 5.7 小时，低于推荐 7-9 小时。
    · 深度睡眠 14.3%，略低于理想范围（15-25%）。

  🔗 交叉关联分析
    · HRV 低（7.9）+ 睡眠不足（5.7h）= 恢复能力严重受损。
      自主神经失衡状态，今天应避免高强度运动或重大决策，
      优先保证今晚睡眠。

  📊 综合评定
    · 健康评分: 65/100 — 一般
      运动活力 █████████░ 23/25
      心血管   ███████░░░ 19/25
      睡眠时长 ██░░░░░░░░ 5/25
      睡眠质量 ███████░░░ 18/25
```

---

## ❓ 常见问题

### 快捷指令报错 "XPC error"

**原因**：「允许共享大量数据」没开。

**解决**：iPhone →「设置」→「快捷指令」→「高级」→ 开启「允许共享大量数据」。如果还不行，重启 iPhone 再试。

### iCloud 登录过期了

AI 操作 iCloud 报错时，直接跟 AI 说"重新登录 iCloud"，它会引导你重新验证。Session 一般能维持几天到几周。

### 中国大陆用户连不上 iCloud

确保环境变量 `ICLOUD_CHINA=1` 已设置（Skill 默认已启用）。

### AI 说"已添加"但 iPhone 上没看到

检查时间线：
1. 待办是每晚 **21:00** 推送到 iCloud Drive，**22:15** iPhone 才导入
2. 如果等不及，跟 AI 说"现在就推送到手机"，它会立即执行同步
3. 确认快捷指令的自动化设置正确，且「运行前询问」已关闭

### 健康数据分析没有结果

1. 确认快捷指令每晚 22:00 有正常运行（手动跑一次看看）
2. 分析命令要在 22:00 之后运行（否则当天数据还没采集）
3. 检查 `iCloud Drive/Shortcuts/Health/` 目录下有没有 `health_YYYY-MM-DD.txt` 文件

### Find My 找不到设备

Find My 只能定位 Apple 设备（iPhone / iPad / Mac / AirTag），不支持安卓或华为设备。

---

## 📋 快捷指令链接汇总

| 功能 | 链接 |
|------|------|
| Health Daily Export（健康数据采集） | https://www.icloud.com/shortcuts/94862224a4b64ca0bf037b89c8f81cb7 |
| Tasks Import（提醒事项导入） | https://www.icloud.com/shortcuts/de68c5443f054355bdb332f246c24a94 |
| Notes Import（备忘录导入） | https://www.icloud.com/shortcuts/2229591d96a849a6ad9b4e44b4b6ce80 |

> ⚠️ 所有链接必须用 **iPhone Safari** 打开！

---

## 🏗️ 项目结构

```
openclaw-with-Apple/
├── SKILL.md                        # AI 行为规则（核心配置文件）
├── scripts/
│   ├── icloud_auth.py              # iCloud 认证管理
│   ├── icloud_tool.py              # 照片 / Drive / 设备
│   ├── icloud_calendar.py          # 日历 (CalDAV)
│   ├── health_tool.py              # 健康数据深度分析（1400+ 行）
│   ├── tasks_tool.py               # 待办事项管理
│   ├── setup_tasks_cron.py         # 定时任务安装
│   └── generate_tasks_shortcut.py  # 快捷指令生成指南
├── tasks_latest.json               # 待办同步文件
└── notes_latest.json               # 备忘录同步文件
```

---

## 🙏 最后

有问题欢迎提 Issue：https://github.com/rtjowo/openclaw-with-Apple/issues