5.4 KiB
5.4 KiB
XCClaw 控制台使用指南
访问地址
http://localhost:8888/console.html
界面概览
控制台采用 Tab 切换设计，包含以下模块：
| Tab | 功能 |
|---|---|
| 任务管理 | 创建、执行一次性任务 |
| 定时任务 | 创建和管理 Cron 循环调度任务 |
| 历史记录 | 查看任务执行历史 |
| 持久会话 | 创建和管理多轮对话会话 |
| 实时日志 | WebSocket 实时推送的任务状态 |
1. 任务管理
用于创建一次性执行的任务。任务创建后不会自动执行，需要手动点击「执行」按钮。
任务类型
| 类型 | 说明 | 使用场景 |
|---|---|---|
| Ephemeral (即时任务) | 一次性任务，执行完成后结束 | 临时性的 AI 问答、代码生成等 |
| Persistent (持久任务) | 可多轮交互的任务会话 | 需要多轮对话才能完成的任务 |
创建任务
- 选择任务类型（即时任务/持久任务）
- 输入任务描述 (Prompt)
- 可选：勾选「创建后自动执行」
- 点击「创建任务」
💡 提示：默认勾选「创建后自动执行」，任务创建后会立即执行。如果需要手动控制执行，取消勾选即可。
执行任务
创建任务后，在任务列表中可以执行以下操作：
| 按钮 | 功能 |
|---|---|
| 详情 | 查看任务的完整信息，包括 Session ID、错误信息等 |
| 执行 | 同步执行任务，等待完成 |
| 异步 | 异步执行任务，立即返回 |
| 中止 | 终止正在执行的任务 |
任务详情
点击「详情」按钮可以查看任务的完整信息：
- 任务ID：任务的唯一标识
- 类型：即时任务/持久任务
- 状态：任务的当前状态
- Session ID：OpenCode 会话 ID，可用于在 OpenCode 界面查看对话详情
- 提示词：任务的完整描述
- 错误信息：任务失败时的错误原因
- 创建/开始/完成时间：任务的时间线
2. 定时任务
用于创建循环执行的定时调度任务。基于 Cron 表达式，在指定时间自动执行任务。
与「任务管理」的区别
| 功能 | 任务管理 | 定时任务 |
|---|---|---|
| 执行方式 | 手动点击执行 | 自动执行 |
| 执行次数 | 一次 | 循环执行 |
| 配置方式 | 创建后手动执行 | 配置 Cron 表达式，自动触发 |
创建定时任务
| 字段 | 说明 |
|---|---|
| 任务ID | 唯一标识符，如 daily_task |
| 任务名称 | 显示名称，如「每日任务」 |
| Cron 表达式 | 执行时间，如 0 9 * * * (每天9点) |
| 执行内容 | 定时执行的 Prompt |
| 启用 | 是否启用此定时任务（未启用则不会执行） |
定时任务列表
表格显示所有定时任务，包含以下信息：
| 列 | 说明 |
|---|---|
| ID | 任务唯一标识 |
| 名称 | 任务显示名称 |
| Cron | 执行时间表达式 |
| 状态 | 已启用 / 已禁用 |
| 提示词 | 执行内容摘要 |
常用 Cron 示例
| 表达式 | 含义 |
|---|---|
0 9 * * * |
每天 9:00 |
0 */2 * * * |
每隔 2 小时 |
0 9 * * 1-5 |
工作日 9:00 |
*/30 * * * * |
每隔 30 分钟 |
3. 历史记录
查看所有已完成的任务执行历史记录。
功能说明
- 查看历史：显示所有任务的执行记录，包括类型、描述、状态、时间等
- 显示条数：可自定义显示的记录数量
- 清空历史：一键清空所有历史记录
任务状态说明
| 状态 | 说明 |
|---|---|
pending |
待执行 |
running |
执行中 |
completed |
已完成 |
failed |
执行失败 |
aborted |
已中止 |
4. 持久会话
创建可多轮交互的对话会话。与「任务管理」中的即时任务不同，持久会话可以多次发送消息，保持上下文连贯。
与即时任务的区别
| 特性 | 即时任务 | 持久会话 |
|---|---|---|
| 交互次数 | 单次 | 多次 |
| 上下文 | 不保持 | 自动保持 |
| 适用场景 | 简单问答 | 复杂任务、多轮对话 |
使用流程
- 创建会话：输入会话名称（可选），点击「创建」
- 发送消息：点击会话的「发消息」按钮
- 选择发送方式：
- 同步发送：等待 AI 响应返回后再操作
- 异步发送：立即返回，任务在后台执行
5. 实时日志
通过 WebSocket 实时显示任务状态和系统消息。
显示内容
- 任务创建、执行、完成的实时通知
- WebSocket 连接状态变化
- 操作日志和错误信息
连接状态
页面左上角显示 WebSocket 连接状态：
- 已连接 - 绿色圆点，正常接收消息
- 未连接 - 红色圆点，需要刷新页面重连
快速参考
功能对比
| 需求 | 推荐功能 |
|---|---|
| 临时性的 AI 问答 | 任务管理 → 即时任务 |
| 需要多轮对话的复杂任务 | 任务管理 → 持久任务 |
| 每天定时执行某任务 | 定时任务 |
| 查看任务执行历史 | 历史记录 |
| 实时监控任务状态 | 实时日志 |
故障排查
| 问题 | 解决方法 |
|---|---|
| 页面无法访问 | 确认 HTTP 服务运行在 8888 端口 |
| API 请求失败 | 确认 XCClaw 服务运行在 3005 端口 |
| WebSocket 未连接 | 检查网络连接，刷新页面 |
| 任务执行失败 | 查看健康检查确认 OpenCode 服务正常 |