XCClaw/README.md

XCClaw

基于 OpenCode Agent 的本地 AI 任务调度系统。

核心理念

以 OpenCode 会话为最小执行单元，通过多种触发方式调度任务，实现本地化的 AI 任务执行系统。

功能特性

• 多种会话类型：即时会话、常驻会话、定时会话
• 任务调度：支持即时执行、异步执行、定时执行
• REST API：完整的 Web API 接口
• Cron 定时任务：基于 APScheduler 的定时任务

快速开始

安装依赖

pip install -r requirements.txt

启动服务

1. 首先确保 OpenCode 服务已启动（默认端口 4096）：

opencode serve --port 4096 --hostname 127.0.0.1

2. 启动 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 监听端口

API 文档

健康检查

GET /api/xcclaw/health

任务管理

创建任务

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

定时任务

创建定时任务

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}

项目结构

xcclaw/
├── app/
│   ├── api/          # API 路由
│   ├── core/         # 配置、日志
│   ├── models/       # 数据模型
│   ├── services/     # 核心服务
│   │   ├── opencode_client.py   # OpenCode API 客户端
│   │   ├── scheduler.py          # 定时任务调度
│   │   └── session_manager.py   # 会话管理
│   └── main.py       # FastAPI 入口
├── docs/              # 文档
├── requirements.txt   # 依赖
└── README.md

License

MIT