XCClaw
基于 OpenCode Agent 的本地 AI 任务调度系统。
核心理念
以 OpenCode 会话为最小执行单元，通过多种触发方式调度任务，实现本地化的 AI 任务执行系统。
功能特性
- 多种会话类型：即时会话（Ephemeral）、持久会话（Persistent）、定时任务（Scheduled）
- 任务执行模式：同步执行、异步执行
- 任务管理：任务创建、执行、中止、历史记录查询
- 定时调度：基于 APScheduler 的 Cron 定时任务
- 实时推送：WebSocket 实时推送任务状态
- 数据持久化：任务、定时调度、持久会话、历史记录自动持久化
- REST API：完整的 Web API 接口
快速开始
启动前端控制台
XCClaw 提供 Web 前端控制台，可视化管理任务、会话和定时调度。
- 启动 HTTP 服务（控制台页面）：
python -m http.server 8888
控制台功能：
- 任务管理：创建、执行、中止任务
- 定时任务：创建和管理 Cron 定时任务
- 历史记录：查看任务执行历史
- 持久会话：创建和管理多轮对话会话
- 实时日志：WebSocket 实时推送任务状态
详细使用说明见 控制台使用指南
安装依赖
pip install -r requirements.txt
启动服务
- 首先确保 OpenCode 服务已启动（默认端口 4096）：
opencode serve --port 4096 --hostname 127.0.0.1
- 启动 XCClaw 服务（默认端口 3005）：
python -m app.main
或指定配置：
XCCLAW_OPENCODE_PORT=4096 XCCLAW_APP_PORT=3005 python -m app.main
配置说明
可通过环境变量配置：
| 环境变量 | 默认值 | 说明 |
|---|---|---|
XCCLAW_OPENCODE_HOST |
127.0.0.1 | OpenCode 服务地址 |
XCCLAW_OPENCODE_PORT |
4096 | OpenCode 服务端口 |
XCCLAW_OPENCODE_PASSWORD |
- | OpenCode 访问密码 |
XCCLAW_APP_HOST |
0.0.0.0 | XCClaw 监听地址 |
XCCLAW_APP_PORT |
3005 | XCClaw 监听端口 |
XCCLAW_DATA_DIR |
~/Documents/XCDesktop/xcclaw | 数据存储目录 |
API 文档
健康检查
GET /api/xcclaw/health
返回示例：
{
"status": "ok",
"opencode": {"status": "ok", "version": "..."}
}
WebSocket 实时推送
WS /api/xcclaw/ws
实时推送任务状态变化。
任务管理
创建任务
POST /api/xcclaw/task
{
"type": "ephemeral", # ephemeral | persistent | scheduled
"prompt": "你的任务描述"
}
执行任务（同步）
POST /api/xcclaw/task/{task_id}/execute
执行任务（异步）
POST /api/xcclaw/task/{task_id}/execute_async
中止任务
POST /api/xcclaw/task/{task_id}/abort
获取任务
GET /api/xcclaw/task/{task_id}
获取任务列表
GET /api/xcclaw/task
定时任务
创建定时任务
POST /api/xcclaw/schedule
{
"id": "unique-id",
"name": "任务名称",
"cron": "0 9 * * *", # Cron 表达式
"prompt": "定时执行的提示词",
"enabled": true
}
列出定时任务
GET /api/xcclaw/schedule
删除定时任务
DELETE /api/xcclaw/schedule/{schedule_id}
任务历史
获取历史记录
GET /api/xcclaw/history?limit=10
清空历史记录
DELETE /api/xcclaw/history
持久会话
创建持久会话
POST /api/xcclaw/persistent?name=我的会话
列出持久会话
GET /api/xcclaw/persistent
删除持久会话
DELETE /api/xcclaw/persistent/{session_id}
发送消息（同步）
POST /api/xcclaw/persistent/{session_id}/message?text=你的消息
发送消息（异步）
POST /api/xcclaw/persistent/{session_id}/message_async?text=你的消息
项目结构
xcclaw/
├── app/
│ ├── api/ # API 路由
│ │ └── routes.py # 所有 API 端点
│ ├── core/ # 核心配置
│ │ ├── config.py # 配置管理
│ │ └── logging.py # 日志配置
│ ├── models/ # 数据模型
│ │ └── session.py # 会话、任务相关模型
│ ├── services/ # 核心服务
│ │ ├── opencode_client.py # OpenCode API 客户端
│ │ ├── scheduler.py # 定时任务调度
│ │ ├── session_manager.py # 任务/会话管理
│ │ ├── persistent_session.py # 持久会话管理
│ │ ├── history.py # 任务历史记录
│ │ ├── storage.py # JSON 数据持久化
│ │ └── websocket_manager.py # WebSocket 管理
│ └── main.py # FastAPI 应用入口
├── tests/ # 测试用例
├── docs/ # 文档
│ └── console-guide.md # 控制台使用指南
├── console.html # Web 前端控制台
├── requirements.txt # Python 依赖
├── pytest.ini # pytest 配置
└── README.md
数据存储
所有数据默认存储在 ~/Documents/XCDesktop/xcclaw/ 目录下：
tasks.json- 任务数据schedules.json- 定时任务配置persistent_sessions.json- 持久会话task_history.json- 任务历史记录
测试
pytest
License
MIT