WizNote 私有化 Skill

概述

此 Skill 为 OpenClaw 提供为知笔记（WizNote）私有化部署的 API 连接能力，支持：

• - ✅ 通过密码登录获取认证 token
• ✅ 笔记的创建、读取、更新、删除（CRUD）
• ✅ 文件夹/分类管理
• ✅ 关键词和标签搜索
• ✅ 完整的错误处理和重试机制

触发条件

当用户提到以下关键词时，自动触发此 Skill：

• - "为知笔记"
• "WizNote"
• "Wiz"
• "笔记管理"
• "创建笔记" / "搜索笔记"

API 调研结果

1. 核心 Endpoint 清单（私有化部署 - 已验证）

参考项目： ConteMan/cwiz

2. 认证方式详解

方式一：密码登录获取 Token（推荐）

请求示例（私有化部署）：
CODEBLOCK0

成功响应：
CODEBLOCK1

流程：

1. 1. 调用登录接口 /as/user/login，传入用户名和密码
2. 从响应中提取 token 和 kbGuid 字段
3. 将 token 存储在环境变量 WIZ_TOKEN 中
4. 将 kbGuid 存储在环境变量 WIZ_KB_GUID 中
5. 后续请求在 URL 参数中携带：INLINECODE17

方式二：直接使用已有 Token

如果已有 token，直接设置环境变量：
CODEBLOCK2

Token 刷新机制

• - Token 有效期：通常为 30 天
• 过期处理：API 返回 401 错误时，需要重新登录获取新 token
• 建议：在脚本中实现自动重新登录逻辑

3. API 版本和稳定性

• - 当前版本：v1（无版本号，直接在根路径下）
• 稳定性：为知笔记 API 相对稳定，向后兼容
• 格式：RESTful API，请求和响应均为 JSON 格式
• 编码：UTF-8

4. 私有化部署特殊配置

端口配置

为知笔记私有化部署支持两种端口配置：

环境变量配置：
CODEBLOCK3

私有化部署注意事项

1. 1. 网络可达性：确保 OpenClaw 服务器能访问为知笔记服务器
2. 防火墙配置：开放相应端口（80 或 9269）
3. HTTPS 支持：私有化部署可能使用 HTTP，云服务使用 HTTPS
4. CORS 配置：如需浏览器访问，需配置 CORS

配置说明

环境变量

此 Skill 依赖以下环境变量：

配置方式

方式一：直接设置环境变量
CODEBLOCK4

方式二：通过 .env 文件
CODEBLOCK5

方式三：在代码中配置
CODEBLOCK6

使用示例

1. 认证 - 通过密码登录获取 Token

CODEBLOCK7

2. 创建笔记

CODEBLOCK8

3. 搜索笔记

CODEBLOCK9

4. 更新笔记

CODEBLOCK10

5. 文件夹管理

CODEBLOCK11

6. 获取笔记内容

CODEBLOCK12

错误处理和重试策略

重试机制

脚本实现了自动重试机制，适用于以下情况：

需要重试的错误：

• - 网络超时（Timeout）
• 连接错误（ConnectionError）
• 服务器错误（500, 502, 503, 504）

不需要重试的错误：

• - 认证失败（401）→ 需要重新登录
• 权限不足（403）→ 需要检查权限
• 资源不存在（404）→ 检查 ID 是否正确
• 参数错误（400）→ 检查请求参数

重试配置：
CODEBLOCK13

错误处理示例

CODEBLOCK14

环境变量缺失提示

CODEBLOCK15

API 不可达降级策略

当 API 不可达时，脚本会：

1. 1. 尝试重试 3 次（指数退避）
2. 如果仍然失败，抛出明确的错误信息
3. 记录错误日志到文件（wiznote_error.log）
4. 返回友好的错误提示，而非原始异常

CODEBLOCK16

日志记录

所有脚本都会记录操作日志到 wiznote.log 文件：

CODEBLOCK17

脚本说明

scripts/wiznote_api.py

核心 API 封装类，提供：

• - WizNoteAPI 类：认证 + 请求封装
• INLINECODE28 - 密码登录获取 token
• INLINECODE29 - 统一请求方法（含重试）

scripts/note_ops.py

笔记操作模块，提供：

• - create_note(title, content, folder, tags) - 创建笔记
• INLINECODE31 - 获取笔记内容
• INLINECODE32 - 更新笔记
• INLINECODE33 - 删除笔记

scripts/folder_ops.py

文件夹管理模块，提供：

• - create_folder(name, parent) - 创建文件夹
• INLINECODE35 - 列出所有文件夹
• INLINECODE36 - 删除文件夹
• INLINECODE37 - 移动笔记

scripts/search.py

搜索功能模块，提供：

• - search_notes(keyword, tag, folder) - 搜索笔记
• INLINECODE39 - 按标签搜索
• INLINECODE40 - 按关键词搜索

最佳实践

1. Token 管理

CODEBLOCK18

2. 批量操作

CODEBLOCK19

3. 错误处理

CODEBLOCK20

故障排查

常见问题

Q1: 提示 "无法连接到为知笔记服务器"

• - 检查 WIZ_ENDPOINT 是否正确
• 检查端口是否开放（80 或 9269）
• 使用 curl 测试连通性：INLINECODE43

Q2: 提示 "认证失败" (401)

• - 检查 WIZ_USER 和密码是否正确
• Token 可能已过期，尝试重新登录
• 检查 token 是否正确设置在 header 中

Q3: 搜索结果为空

• - 检查搜索关键词是否正确
• 确认笔记确实存在
• 检查是否有权限访问该笔记

Q4: 创建笔记失败

• - 检查文件夹路径是否存在
• 检查内容格式（HTML 或 Markdown）
• 查看错误日志 INLINECODE45

参考资源

• - 为知笔记官网
• 为知笔记 GitHub
• 私有化部署文档：请联系为知笔记官方获取

版本历史

• - v1.0.0 (2026-03-26)