常见问题
本文汇总 Wesclaw 用户最常遇到的问题。如果这里没有覆盖你的疑问，请在设置页面反馈或查阅其他文档。
Wesclaw 和普通 Chat 工具有什么区别？
Wesclaw 不是一个简单的"对话窗口"，它是由 wesgine AI Agent 引擎 驱动的完整智能助手平台：
| 能力 | 普通 Chat | Wesclaw |
|---|---|---|
| 对话 | ✅ 基础对话 | ✅ 多轮上下文对话 |
| 记忆 | ❌ 无记忆 | ✅ 四层记忆体系（环境/共识/关于我/角色记忆） |
| 工具调用 | ❌ 或有限 | ✅ 文件读写、终端执行、网页浏览等 |
| 技能系统 | ❌ | ✅ Tier E 引擎内置 + Tier C Cell 级技能 |
| 多 Agent | ❌ | ✅ 多角色协作、任务委派 |
| 设备自动化 | ❌ | ✅ 浏览器自动化、桌面自动化 |
| 数据隔离 | ❌ | ✅ 1 Cell 物理隔离，可导出/迁移 |
| IM 渠道 | ❌ | ✅ 企业微信、飞书、钉钉接入 |
| 定时任务 | ❌ | ✅ Cron 表达式、定期执行 |
什么是 Agent？
Agent（智能体）是 Cell 内的"次级隔离"单元。每个 Agent 拥有独立的认知配置：
- Prompt：系统提示词，定义 Agent 的性格和能力
- Tool ACL：可使用的工具白名单
- Model：使用的 LLM 模型
- Skills：Agent 可调用的技能列表
Wesclaw 提供预置 Agent（通用助手），你也可以创建自定义 Agent：
Agent 的命名空间隔离：
agent://assistant/* — 通用助手的记忆
agent://researcher/* — 研究员的记忆
cell://* — Cell 级共享记忆
通过 /contacts 页面管理 Agent，或通过 cell.Agents() API 进行 CRUD 操作。
什么是 Skill？
Skill（技能）是结构化 Markdown 文件（SKILL.md），用于指导 Agent 完成特定任务。
两个层级
| 层级 | 来源 | 说明 |
|---|---|---|
| Tier E（引擎技能） | wesgine 二进制 embed | 约 7 个，只读，只允许引擎术语 |
| Tier C（Cell 技能） | .wesskill 包上传或应用自带 | 受 MaxSkillsInstalled 限制，业务术语允许 |
Skill 包结构
.wesskill 包:
├── SKILL.md # 必需，name/version 的权威源
├── scripts/ # 可选，辅助脚本
├── templates/ # 可选，模板文件
├── manifest.json # 可选，依赖声明
└── signature.sig # 可选，ed25519 签名
通过 cell.Skills().InstallPackage(ctx, pkg) 安装技能。
什么是 Cell？
Cell 是 wesgine 引擎中完整、独立、可移植的 AI Agent 运行时。
- Wesclaw 桌面版默认创建一个
"main"Cell - 一个 Cell 包含：会话、记忆、技能、知识库、Agent 配置、工作区文件
- Cell 之间物理隔离（AX-1 公理），不共享数据面
- Cell 可以导出为
tar.gz并在另一台机器上导入
Cell = Runtime Instance + Tenant Unit + Portable Snapshot
Wesclaw 桌面版是 N=1 单租户应用，前端不感知 Cell。
什么是记忆？
Wesclaw 的记忆体系是七值闭域，分为四个用户层和三个运行时层：
四个用户层
| 层级 | 标识 | 说明 | 示例 |
|---|---|---|---|
| L1 | environment | 宿主环境信息 | 操作系统、已安装工具 |
| L2 | consensus | 部门/团队共识 | 桌面 N=1 时恒空 |
| L3 | about_me | 关于我的偏好 | "偏好暗色主题" |
| L4 | agent_memory | 角色记忆 | Agent 特有的知识 |
三个运行时层
| 层级 | 标识 | 说明 |
|---|---|---|
| — | session | 会话临时记忆 |
| — | working | 工作缓存 |
| — | unknown | 未识别的层（兜底） |
记忆页面中，七个层的芯片无条件渲染（含计数为 0），确保用户能区分"层是空的"与"层不存在"。
什么是 MCP？
MCP（Model Context Protocol）是连接 AI 与外部工具和数据的标准协议。
在 Wesclaw 中，你可以通过 MCP 接入：
- 第三方数据库查询工具
- 企业内部 API
- 文件管理系统
- 任何支持 MCP 协议的服务
// 注册 MCP Server
cell.MCPs().Upsert(ctx, mcp.ServerConfig{
Name: "my-tool",
Transport: "stdio",
Command: []string{"/path/to/mcp-server"},
})
管理操作：GET /mcp 列表、POST /mcp 注册、DELETE /mcp/{name} 删除、POST /mcp/{name}/probe 探测连通性。
什么是 HITL（人机协作）？
HITL（Human-in-the-Loop）是指在 AI 执行过程中暂停并请求人类决策的机制。
三种触发方式
ask_user：Agent 主动向用户提问browser_wait_for_user：浏览器自动化等待用户操作（如登录）CycleDetector：检测到死循环后询问用户
HITL 不由治理链（Governance）产生，它是 Agent 主动交互的手段。
WES / Org / BYOK 是什么？
这是 Wesclaw 的三种模型来源（Provider 通道）：
| 通道 | 前缀 | 说明 | 适用场景 |
|---|---|---|---|
| WES | wes: | 平台托管 | 开箱即用，按量计费 |
| Org | org: | 组织托管 | 企业统一管理 |
| BYOK | byok: | 自有密钥 | 自带 API Key |
- WES 欠费时，已选 BYOK 模型不受影响，可正常使用
- 模型选择器中，不可用的 WES 模型会标记
disabled - 三种来源统一通过
providerid.IsWES()/IsOrg()/IsCloudManaged()判断
桌面版和云端版有什么区别？
| 特性 | 桌面版（Desktop） | 云端版（SaaS） |
|---|---|---|
| 架构 | Electron + Go 后端 | 独立 HTTP 服务 |
| 通信 | stdio JSON-RPC | HTTP + SSE + JWT |
| 租户 | 1 Cell（"main"） | N Cell（平台分配） |
| exec 工具 | ✅ 可用 | ❌ 默认关闭 |
| 治理 | open（标准） | locked + internal_only |
| 设备自动化 | ✅ Device Agent | ❌ 不支持 |
| 部署 | 用户电脑 | 服务器 |
如何切换账号？
Wesclaw 桌面版遵循 PROD-1 原则：
- 前端不感知 Cell（没有
activeCellstore、没有cell_id注入） - Go 后端
Handler.instance永远绑定 boot 时创建的mainCell - 切换账号 = Go 进程整体重启
不会有 per-RPC cell_id 泄漏。将来接入账号系统时，仍是进程级切换。
如何导出数据？
通过 Cell Export 功能将所有数据打包为 tar.gz：
# API 方式
GET /admin/cells/{id}/export → tar.gz 流
# 导入
POST /admin/cells/import → 新 Cell（支持 ?overwrite=1）
导出包含的内容：
| 内容 | 是否包含 |
|---|---|
| workspace（工作区文件） | ✅ 默认包含（可通过 SkipWorkspace 排除） |
| sessions（会话） | ✅ |
| memory（记忆） | ✅ |
| knowledge（知识库） | ✅ |
| skills（技能） | ✅ |
| .scratch（临时文件） | ❌ 永不包含 |
群聊怎么工作？
群聊支持多用户与多 Agent 在同一对话中协作：
- 群组数据存储在
tc_groups/tc_group_members/tc_group_conversations表中 - 群聊迁移通过
group.Migrate()独立管理（Chain 2，不影响主迁移链） - 群消息遵循与单聊相同的 SSE 流稳定性契约
浏览器自动化怎么工作？
Wesclaw 通过 adapter/playwright/ 适配器实现用户浏览器自动化：
- 配置
CellSpec.Playwright启用 - 安装浏览器扩展，自动连接到 Cell
- Agent 通过
cell.Playwright()Handle 操作浏览器
PUT /playwright/token — 更新扩展 auto-connect token
GET /playwright/status — 查看连接状态
Playwright 用于需要用户登录态的场景；匿名抓取使用 HeadlessBrowser。
桌面自动化怎么工作？
桌面自动化通过 Device Agent 实现，是 Wesclaw 独有能力：
- Electron main 进程内嵌 Device Agent 二进制
- 通过
cell.MCPs().Upsert注册到 Cell - 提供的 MCP 工具：
| 工具 | 功能 |
|---|---|
wesclaw_desktop_click | 点击 UI 元素 |
wesclaw_open_app | 打开应用 |
wesclaw_clipboard_read/write | 剪贴板操作 |
wesclaw_screenshot | 截屏 |
wesclaw_notify | 系统通知 |
wesclaw_show_file | Finder/Explorer 定位 |
定时任务怎么工作？
定时任务通过 Cron 子系统实现：
配置方式
- 声明式：
CellSpec.Cron在 Cell 首次 boot 时播种 - 运行时：
cell.Cron().Add()动态添加
支持的调度格式
| 格式 | 示例 |
|---|---|
| Cron 表达式 | "0 9 * * 1" |
| Duration | "30m", "2h", "1d" |
| Every 短语 | "every 2h", "every monday 9am" |
| ISO 时间戳 | "2026-06-01T09:00:00Z"（一次性） |
管理操作
GET /cron — 任务列表
POST /cron — 添加任务
PATCH /cron/{id} — 更新任务
DELETE /cron/{id} — 删除任务
POST /cron/{id}/trigger — 立即触发
声明式播种是出生声明，写入存储后声明不再被读——运行时存储是唯一权威源。