nextcloud

Nextcloud 通过 WebDAV + OCS API 管理文件和文件夹。在以下情况下使用：(1) 创建、读取、写入、重命名、移动、复制或删除文件/文件夹，(2) 列出或搜索目录内容，(3) 切换收藏夹或管理系统标签，(4) 检查存储配额。不适用于：Nextcloud Talk、日历/联系人（使用 CalDAV）、应用程序管理（需要管理员）、大型二进制传输或创建共享链接（默认情况下不包括共享功能 - 请参阅自述文件）。

## 概述（中文）

Nextcloud 通过 WebDAV + OCS API 管理文件和文件夹。在以下情况下使用：(1) 创建、读取、写入、重命名、移动、复制或删除文件/文件夹，(2) 列出或搜索目录内容，(3) 切换收藏夹或管理系统标签，(4) 检查存储配额。不适用于：Nextcloud Talk、日历/联系人（使用 CalDAV）、应用程序管理（需要管理员）、大型二进制传输或创建共享链接（默认情况下不包括共享功能 - 请参阅自述文件）。

## 原文

# Nextcloud Skill

Full Nextcloud client: WebDAV (files/folders) + OCS (tags, user info). Zero external dependencies - stdlib only (urllib).
Credentials: `~/.openclaw/secrets/nextcloud_creds` · Config: `~/.openclaw/config/nextcloud/config.json`

## Trigger phrases

Load this skill immediately when the user says anything like:

- "upload / save / write this file on Nextcloud / NC / cloud"
- "create a folder on Nextcloud", "mkdir in NC"
- "list / browse / show what's in [folder] on Nextcloud"
- "search for [file] in NC", "find [file] on Nextcloud"
- "read / get / download [file] from Nextcloud"
- "rename / move / copy [file] on Nextcloud"
- "check my storage quota", "how much space on NC"
- "tag this file", "mark as favorite on Nextcloud"

## Quick Start

```bash
python3 scripts/nextcloud.py config    # verify credentials + active config
python3 scripts/nextcloud.py quota     # test connection + show storage
python3 scripts/nextcloud.py ls /      # list root directory
```

## Setup

```bash
python3 scripts/setup.py       # interactive: credentials + permissions + connection test
python3 scripts/init.py        # validate all configured permissions against live instance
```

> init.py only runs write/delete tests when both `allow_write=true` and `allow_delete=true`. When `allow_delete=false`, write tests are skipped - no test artifacts are created or left behind.

**Manual** - `~/.openclaw/secrets/nextcloud_creds` (chmod 600):
```
NC_URL=https://cloud.example.com
NC_USER=username
NC_APP_KEY=app-password
```
App password: Nextcloud → Settings → Security → App passwords.

**config.json** - behavior restrictions:

| Key | Default | Effect |
|-----|---------|--------|
| `base_path` | `"/"` | Restrict agent to subtree (e.g. `"/Jarvis"`) |
| `allow_write` | `false` | mkdir, write, rename, copy (enable explicitly) |
| `allow_delete` | `false` | delete files and folders (enable explicitly) |
| `readonly_mode` | `false` | override: block all writes regardless of above |

> **Safe defaults:** both `allow_write` and `allow_delete` are `false` by default. Enable each explicitly only when needed. Combine with a restricted `base_path` (e.g. `"/Jarvis"`) to limit the agent's scope.
> **Share capability** is not included by default. See README for instructions on how to restore it if needed.

## Storage & credentials

The skill reads and writes the following paths. All usage is intentional and documented:

| Path | Written by | Purpose |
|------|-----------|---------|
| `~/.openclaw/secrets/nextcloud_creds` | `setup.py` | Nextcloud credentials (NC_URL, NC_USER, NC_APP_KEY). chmod 600. Never committed. |
| `~/.openclaw/config/nextcloud/config.json` | `setup.py` | Behavior restrictions (base_path, allow_write, allow_delete, readonly_mode). No secrets. Not in skill dir - survives clawhub updates. |

Credentials can also be provided via environment variables (`NC_URL`, `NC_USER`, `NC_APP_KEY`) instead of the creds file. The skill checks env vars first.

**Cleanup on uninstall:** `clawhub uninstall nextcloud-files` removes the skill directory. To also remove credentials and config:
```bash
python3 scripts/setup.py --cleanup
```
On reinstall, any existing config at `~/.openclaw/config/nextcloud/config.json` is picked up automatically.

## Module usage

```python
from scripts.nextcloud import NextcloudClient
nc = NextcloudClient()
nc.write_file("/Jarvis/notes.md", "# Notes\n...")
nc.mkdir("/Jarvis/Articles")
items = nc.list_dir("/Jarvis")
```

## CLI reference

```bash
# Files & folders
python3 scripts/nextcloud.py mkdir /path/folder
python3 scripts/nextcloud.py write /path/file.md --content "# Title"
python3 scripts/nextcloud.py write /path/file.md --file local.md
python3 scripts/nextcloud.py write /path/file.md --content "new entry" --append
python3 scripts/nextcloud.py read  /path/file.md
python3 scripts/nextcloud.py rename /old /new
python3 scripts/nextcloud.py copy   /src /dst
python3 scripts/nextcloud.py delete /path
python3 scripts/nextcloud.py exists /path          # exit 0/1

# Listing & search
python3 scripts/nextcloud.py ls /path --depth 2 --json
python3 scripts/nextcloud.py search "keyword" --path /folder --limit 20

# Favorites & tags
python3 scripts/nextcloud.py favorite /path/file.md
python3 scripts/nextcloud.py tags
python3 scripts/nextcloud.py tag-create "research"
python3 scripts/nextcloud.py tag-assign <file_id> <tag_id>

# Account
python3 scripts/nextcloud.py quota
python3 scripts/nextcloud.py config
```

## Templates

### Structured workspace setup
```bash
python3 scripts/nc_setup.py --root Jarvis --folders Articles,LinkedIn,Recherche,Veille
```

### Append to a running log
```python
nc.append_to_file("/Jarvis/log.md", f"\n## {today}\n{entry}\n")
```

### Read and update a JSON list
```python
items = nc.read_json("/Jarvis/Veille/articles.json")
items["articles"].append(new_article)
nc.write_json("/Jarvis/Veille/articles.json", items)
```

### Tag a file after creation
```python
ls = nc.list_dir("/Jarvis/Articles", depth=1)
file_id = next(f["file_id"] for f in ls if f["name"] == "article.md")
tags = nc.get_tags()
tag_id = next(t["id"] for t in tags if t["name"] == "published")
nc.assign_tag(file_id, tag_id)
```

## Ideas
- Sandbox the agent with `base_path: "/Jarvis"` - it can't touch anything else
- Store agent-produced Markdown files and auto-share a read-only link in the reply
- Use `append_to_file` for rolling logs or changelogs
- Use `write_json` + `read_json` for persistent state between sessions
- Auto-tag files by category (research / draft / published)

## Combine with

| Skill | Workflow |
|-------|----------|
| **ghost** | Write a post → save Markdown draft to NC → publish to Ghost |
| **summarize** | Summarize a URL → save summary as `.md` to NC |
| **gmail** | Receive an attachment → save to NC for archiving |
| **obsidian** | Sync Obsidian vault notes to NC for remote backup |
| **self-improving-agent** | Log agent learnings to NC for persistent, searchable history |

## API reference
See `references/api.md` for WebDAV/OCS endpoint details, PROPFIND properties, and error codes.

## Troubleshooting
See `references/troubleshooting.md` for common errors and fixes.

---

## 中文说明

# Nextcloud Skill

完整的 Nextcloud 客户端：WebDAV（文件/文件夹）+ OCS（标签、用户信息）。零外部依赖——仅使用标准库（urllib）。
凭据：`~/.openclaw/secrets/nextcloud_creds` · 配置：`~/.openclaw/config/nextcloud/config.json`

## 触发短语

当用户说出类似以下内容时，立即加载此技能：

- "upload / save / write this file on Nextcloud / NC / cloud"
- "create a folder on Nextcloud", "mkdir in NC"
- "list / browse / show what's in [folder] on Nextcloud"
- "search for [file] in NC", "find [file] on Nextcloud"
- "read / get / download [file] from Nextcloud"
- "rename / move / copy [file] on Nextcloud"
- "check my storage quota", "how much space on NC"
- "tag this file", "mark as favorite on Nextcloud"

## 快速开始

```bash
python3 scripts/nextcloud.py config    # verify credentials + active config
python3 scripts/nextcloud.py quota     # test connection + show storage
python3 scripts/nextcloud.py ls /      # list root directory
```

## 安装设置

```bash
python3 scripts/setup.py       # interactive: credentials + permissions + connection test
python3 scripts/init.py        # validate all configured permissions against live instance
```

> 只有当 `allow_write=true` 和 `allow_delete=true` 同时成立时，init.py 才会运行写入/删除测试。当 `allow_delete=false` 时，跳过写入测试——不会创建或遗留任何测试产物。

**手动配置** - `~/.openclaw/secrets/nextcloud_creds`（chmod 600）：
```
NC_URL=https://cloud.example.com
NC_USER=username
NC_APP_KEY=app-password
```
应用密码：Nextcloud → Settings → Security → App passwords。

**config.json** - 行为限制：

| 键 | 默认值 | 作用 |
|-----|---------|--------|
| `base_path` | `"/"` | 将代理限制在某个子树（例如 `"/Jarvis"`） |
| `allow_write` | `false` | mkdir、写入、重命名、复制（需显式启用） |
| `allow