Wolai API Skill

通过 wolai Open API 操作 wolai 笔记，支持读取页面/块内容、创建块（写入内容）、获取数据库、向数据库插入数据、获取/刷新 Token。当用户需要读取 wolai 页面、向 wolai 写入内容、操作 wolai 数据库、或与 wolai 进行任何数据交互时使用此 skill。触发场景：「读取...

Security Scan

The skill's instructions are coherent for talking to Wolai via its Open API, but the package metadata omits required credentials and references a missing local doc, so the bundle is inconsistent and needs clarification before trusting it with secrets.

Purpose & Capability

The name/description match the actual behavior: the SKILL.md instructs how to call Wolai Open API to read/write pages and databases. However the registry metadata reports no required environment variables or primary credential while the SKILL.md explicitly requires a WOLAI_TOKEN (and shows how to obtain it using appId/appSecret). This mismatch is an incoherence in the package manifest.

Instruction Scope

The instructions are narrowly scoped to making REST calls to https://openapi.wolai.com/v1 using PowerShell and to checking the WOLAI_TOKEN env var. They do not request reading unrelated system files or exfiltrating data to other endpoints. Concerns: (1) the SKILL.md references a local file references/api.md for detailed parameters but that file is not present in the published manifest, reducing transparency; (2) the guidance is PowerShell-centric (Windows), which may not work on non-Windows agents.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest disk/write risk. Runtime actions are PowerShell REST calls; nothing is downloaded or extracted by the skill bundle itself.

Credentials

The SKILL.md requires a persistent WOLAI_TOKEN (and shows how to exchange appId/appSecret for it). The token is described as permanent (expire_time: -1), making it a high-value secret. But the registry metadata lists no required env vars or primary credential — an inconsistency. Asking users to store a permanent token in the agent config (openclaw config set env.WOLAI_TOKEN ...) without declaring it in metadata is disproportionate and should be fixed/documented. appId/appSecret are also sensitive but are only used to obtain the token; this is expected for API access but must be clearly declared.

Persistence & Privilege

The skill is not force-included (always: false). The SKILL.md suggests persisting WOLAI_TOKEN into the agent configuration (openclaw config set ...), which will store the secret persistently — this is normal for API skills but increases risk if that storage is shared or not encrypted. The skill is invocable autonomously by agents (disable-model-invocation: false), which is the platform default; combine that with a persisted permanent token only if you trust the agent environment.

What to consider before installing

This skill appears to be a straightforward PowerShell-based client for the Wolai Open API, but the published metadata is incomplete and the instructions reference a missing local document. Before installing: 1) Confirm that the skill truly needs WOLAI_TOKEN and request the publisher update the package metadata to declare WOLAI_TOKEN (and any other required secrets). 2) Prefer creating an app with the minimal permissions necessary; avoid reusing highly privileged or production tokens. 3) Note the token described is permanent — avoid storing permanent secrets in shared agent configs or use a secrets vault/rotating token if possible. 4) Be aware this skill expects PowerShell; if your agent runs on Linux/macOS, verify compatibility. 5) Ask the publisher for the referenced references/api.md or API docs and for clarification about where and how the token is stored (is it encrypted in agent config?). If you cannot verify these points, treat the skill as untrusted and do not store sensitive Wolai credentials in the agent.

通过 wolai Open API（RESTful）操作 wolai 的块、页面、数据库。

Base URL：https://openapi.wolai.com/v1

详细接口参数见 references/api.md。

Setup

1. 创建应用并获取 Token

1. 前往 https://www.wolai.com/dev 创建应用，选择所需权限（读取/插入/更新页面内容）
2. 创建后得到 App ID 和 App Secret
3. 调用 POST /token 换取 app_token（Token 永久有效，expire_time: -1）
4. 将 Token 存入环境变量：

WOLAI_TOKEN=your_app_token

在 QClaw/OpenClaw 中配置：

openclaw config set env.WOLAI_TOKEN "your_app_token"

2. 团队空间需添加应用权限

团队空间中，每个页面需单独添加应用： 页面右上角 → 页面协作 → 成员协作→应用权限 → 添加应用

个人空间默认拥有全部页面权限，无需此步骤。

凭证预检

每次调用前先检查 Token：

if (-not $env:WOLAI_TOKEN) {
    Write-Host "缺少 WOLAI_TOKEN，请按 Setup 步骤配置"
    exit 1
}

API 调用方式

所有请求统一使用 PowerShell（Windows 环境），Token 放在 Authorization Header：

function Invoke-WolaiApi {
    param(
        [string]$Method = "GET",
        [string]$Path,
        [hashtable]$Body = $null
    )
    # ⚠️ 必须强制 UTF-8，否则中文内容会变成问号
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
    $OutputEncoding = [System.Text.Encoding]::UTF8

    $headers = @{
        "Authorization" = $env:WOLAI_TOKEN
        "Content-Type"  = "application/json; charset=utf-8"
    }
    $uri = "https://openapi.wolai.com/v1$Path"
    if ($Body) {
        $bodyBytes = [System.Text.Encoding]::UTF8.GetBytes(($Body | ConvertTo-Json -Depth 10))
        Invoke-RestMethod -Method $Method -Uri $uri -Headers $headers -Body $bodyBytes
    } else {
        Invoke-RestMethod -Method $Method -Uri $uri -Headers $headers
    }
}

接口决策表

用户意图	接口	说明
读取页面/块内容	GET /blocks/{id}	id 为页面 ID 或块 ID
读取页面下所有子块	GET /blocks/{id}/children	支持分页
向页面写入/追加内容	POST /blocks	需指定 parent_id
读取数据库	GET /databases/{id}	支持分页、筛选、排序
向数据库插入行	POST /databases/{id}/rows
获取 Token	POST /token	需要 appId + appSecret
刷新 Token	PUT /token	Token 泄露时使用

常用工作流

读取页面内容

# 页面 ID 从 URL 获取：wolai.com/ 后面的部分即为页面 ID
$pageId = "oaBQLqSBaMbS6S4NX4fJU7"

# 获取页面块信息
$page = Invoke-WolaiApi -Method GET -Path "/blocks/$pageId"
$page.data

# 获取页面所有子块（内容列表）
$children = Invoke-WolaiApi -Method GET -Path "/blocks/$pageId/children"
$children.data

向页面写入内容（创建块）

# 在指定页面末尾追加一段文字
Invoke-WolaiApi -Method POST -Path "/blocks" -Body @{
    parent_id = "oaBQLqSBaMbS6S4NX4fJU7"  # 目标页面 ID
    blocks = @{
        type    = "text"
        content = "Hello from OpenClaw!"
    }
}

读取数据库

$dbId = "your_database_id"
$db = Invoke-WolaiApi -Method GET -Path "/databases/$dbId"
$db.data

向数据库插入数据

Invoke-WolaiApi -Method POST -Path "/databases/$dbId/rows" -Body @{
    rows = @(
        @{ "字段名" = "值1"; "另一字段" = "值2" }
    )
}

获取 Token（首次配置）

$resp = Invoke-RestMethod -Method POST `
    -Uri "https://openapi.wolai.com/v1/token" `
    -Headers @{ "Content-Type" = "application/json" } `
    -Body (@{ appId = "your_app_id"; appSecret = "your_app_secret" } | ConvertTo-Json)
$resp.data.app_token  # 保存此值到 WOLAI_TOKEN

接口限制

• 频率：同一用户 5次/秒
• 批量获取：一次最多 200 条，超出用分页（has_more + next_cursor）
• 批量创建/更新：一次最多 20 条
• 删除：每次只能删除 1 条

用量限制（每小时/每月）因套餐不同，详见 references/api.md。

错误处理

错误码	含义	建议处理
17001	缺少参数	检查必填字段
17002	参数错误	检查参数格式
17003	无效 Token	检查 WOLAI_TOKEN 是否正确
17004	获取资源失败	检查 ID 是否正确
17005	资源未找到	检查页面/块 ID
17006	服务器内部错误	稍后重试
17007	请求过于频繁	降低调用频率（≤5次/秒）
17008	请求体过大	拆分为多次请求
17010	不支持的块类型	检查 type 字段，见 references/api.md
17011	权限不足	团队空间需在页面添加应用权限

注意事项

• 页面 ID 从 URL 获取：wolai.com/ 后面的部分即为 ID
• Token 永久有效（expire_time: -1），泄露后调用 PUT /token 刷新
• 团队空间每个页面都需单独添加应用，个人空间无需此操作
• 块类型详见 references/api.md 的「块类型说明」章节