Synology Calendar Plugin Openclaw

Name: Synology Calendar Plugin Openclaw
Rating: 3.5 (1 reviews)
Author: fatatalia

By fatatalia 👁 38 views ▲ 0 votes

OpenClaw plugin: Synology Calendar integration via CalDAV

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "load": {
      "paths": ["/path/to/synology-calendar"]
    },
    "allow": ["synology-calendar"],
    "entries": {
      "synology-calendar": {
        "enabled": true,
        "config": {
          "url": "https://your-nas:5001/caldav/",
          "username": "your-dsm-account",
          "calendars": {
            "home": "yourusername%40domain.com/home",
            "work": "yourusername%40domain.com/rxjxbkp",
            "personal": "yourusername%40domain.com/smocqxsc"
          }
        }
      }
    }
  }
}

README

# Synology Calendar — OpenClaw Plugin

群晖 NAS 日历系统的 OpenClaw 插件，通过 CalDAV 协议对接群晖 Calendar 套件，在聊天对话中直接管理日程。

[OpenClaw]: https://github.com/openclaw/openclaw
[CalDAV]: https://en.wikipedia.org/wiki/CalDAV

## Features

- **查日程** — 查询指定日期范围内的日程事件
- **加日程** — 创建新的日历事件
- **改日程** — 按 UID 修改已有事件
- **删日程** — 按 UID 删除事件
- **多日历** — 支持家庭/工作/个人三个日历

## Requirements

- OpenClaw >= 2026.3.24-beta.2
- Synology NAS with Calendar package (CalDAV enabled)
- Node.js >= 22.22.3

## Installation

### 1. 克隆项目

```bash
git clone https://github.com/fatatalia/synology-calendar-plugin-openclaw.git
cd synology-calendar
npm install
```

### 2. 编译

```bash
npx tsc
```

### 3. 配置 OpenClaw

在 `openclaw.json` 中添加：

```json
{
  "plugins": {
    "load": {
      "paths": ["/path/to/synology-calendar"]
    },
    "allow": ["synology-calendar"],
    "entries": {
      "synology-calendar": {
        "enabled": true,
        "config": {
          "url": "https://your-nas:5001/caldav/",
          "username": "your-dsm-account",
          "calendars": {
            "home": "yourusername%40domain.com/home",
            "work": "yourusername%40domain.com/rxjxbkp",
            "personal": "yourusername%40domain.com/smocqxsc"
          }
        }
      }
    }
  }
}
```

### 4. 设置密码

密码通过环境变量传入，与 OpenClaw 的 API Key 存储方案一致：

```json
{
  "env": {
    "CALDAV_PASSWORD": "your-password-here"
  }
}
```

也可以在 LaunchDaemon 或 systemd 中设置 `CALDAV_PASSWORD` 环境变量。

### 5. 重启 Gateway

```bash
openclaw gateway restart
```

## Tools

插件注册 4 个 agent tool：

### `calendar_query_events`

查询指定日期范围内的日程事件。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `start_date` | string | ✅ | 开始日期 (YYYY-MM-DD 或 ISO 8601) |
| `end_date` | string | ❌ | 结束日期。默认 start_date 当天结束 |
| `calendar` | string | ❌ | 日历名：`home` / `work` / `personal`，默认 `home` |

### `calendar_create_event`

创建新的日历事件。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `title` | string | ✅ | 事件标题 |
| `start_time` | string | ✅ | 开始时间 (ISO 8601，支持时区) |
| `end_time` | string | ✅ | 结束时间 (ISO 8601，支持时区) |
| `calendar` | string | ❌ | 日历名，默认 `home` |
| `description` | string | ❌ | 事件描述 |
| `location` | string | ❌ | 事件地点 |

### `calendar_update_event`

按 UID 更新已有事件。只传需要修改的字段即可。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `uid` | string | ✅ | 要更新的事件 UID |
| `title` | string | ❌ | 新标题 |
| `start_time` | string | ❌ | 新开始时间 |
| `end_time` | string | ❌ | 新结束时间 |
| `description` | string | ❌ | 新描述 |
| `location` | string | ❌ | 新地点 |
| `calendar` | string | ❌ | 日历名 |

### `calendar_delete_event`

按 UID 删除事件。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `uid` | string | ✅ | 要删除的事件 UID |

## 时区处理

插件使用 UTC 存储时间（iCal 标准），群晖 Calendar 自动转换成本地时区显示。

- 传入带时区的 ISO 时间（如 `2026-07-31T14:00:00+08:00`），插件自动转为 UTC
- 也接受无时区的时间字符串，由系统时区决定
- 全天事件使用 `VALUE=DATE` 格式，不受时区影响

## 日历映射

配置中的 `calendars` 字段定义日历名到 CalDAV 路径的映射：

```json
{
  "calendars": {
    "home": "maya%40aaila.wang/home",
    "work": "maya%40aaila.wang/rxjxbkp",
    "personal": "maya%40aaila.wang/smocqxsc"
  }
}
```

获取日历路径的方法：通过任何 CalDAV 客户端（如 Mac 日历、Thunderbird）连接到群晖后，查看日历订阅 URL。

## Project Structure

```
synology-calendar/
├── README.md
├── package.json
├── openclaw.plugin.json   # OpenClaw 插件清单
├── tsconfig.json
├── src/
│   ├── index.ts           # 插件入口 — defineToolPlugin
│   ├── caldav.ts          # CalDAV HTTP 客户端
│   └── types.ts           # 类型定义
└── dist/                  # 编译输出
```

## Development

```bash
# 安装依赖
npm install

# 编译
npx tsc

# 验证
openclaw plugins list | grep synology-calendar
openclaw plugins inspect synology-calendar
```

## License

MIT

integration