XCClaw/docs/console-guide.md

XCClaw 控制台使用指南

访问地址

http://localhost:8888/console.html

界面概览

控制台采用 Tab 切换设计，包含以下模块：

Tab	功能
任务管理	创建、执行、管理即时/持久/定时任务
定时任务	创建和管理 Cron 定时任务
历史记录	查看任务执行历史
持久会话	创建和管理多轮对话会话
实时日志	WebSocket 实时推送的任务状态

---

1. 任务管理

创建任务

1. 选择任务类型：

   • Ephemeral (即时任务)：一次性任务，执行后结束
   • Persistent (持久任务)：可多轮交互的任务
   • Scheduled (定时任务)：需要配合定时任务模块使用

2. 输入任务描述 (Prompt)

3. 点击「创建任务」

执行任务

创建任务后，在任务列表中可以：

按钮	功能
执行	同步执行任务，等待完成
异步	异步执行任务，立即返回
中止	终止正在执行的任务

任务状态

• pending - 待执行
• running - 执行中
• completed - 已完成
• failed - 执行失败
• aborted - 已中止

---

2. 定时任务

创建定时任务

字段	说明
任务ID	唯一标识符，如 daily_task
任务名称	显示名称，如「每日任务」
Cron 表达式	执行时间，如 0 9 * * * (每天9点)
执行内容	定时执行的 Prompt
启用	是否启用此定时任务

常用 Cron 示例

表达式	含义
0 9 * * *	每天 9:00
0 */2 * * *	每隔 2 小时
0 9 * * 1-5	工作日 9:00
*/30 * * * *	每隔 30 分钟

---

3. 历史记录

• 查看所有已完成的任务记录
• 支持限制显示条数
• 可清空历史记录

---

4. 持久会话

创建会话

输入会话名称（可选），点击「创建」

发送消息

1. 在列表中找到目标会话
2. 点击「发消息」按钮
3. 输入消息内容
4. 选择发送方式：
   • 同步发送：等待响应返回
   • 异步发送：立即返回，任务在后台执行

---

5. 实时日志

通过 WebSocket 实时显示：

• 任务状态变化
• WebSocket 连接状态
• 操作日志

---

快捷操作

• 自动刷新：健康检查和任务列表每 5 秒自动刷新
• WebSocket：页面左上角显示连接状态

---

故障排查

问题	解决方法
页面无法访问	确认 HTTP 服务运行在 8888 端口
API 请求失败	确认 XCClaw 服务运行在 3005 端口
WebSocket 未连接	检查网络连接，刷新页面
任务执行失败	查看健康检查确认 OpenCode 服务正常