ai-status-light/docs/api.md

OpenCode Monitor API 接口文档

基础信息

• Base URL: http://localhost:8080
• Content-Type: application/json
• 响应格式: { "code": 0, "message": "ok", "data": {} }

接口列表

1. 健康检查

GET /api/health

响应示例:

{
  "code": 0,
  "message": "ok"
}

2. 获取所有 MQTT 配置

GET /api/mqtt

响应示例:

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "broker": "tcp://127.0.0.1:1883",
      "client_id": "opencode-monitor",
      "username": "user",
      "password": "pass",
      "topic": "opencode/status",
      "enabled": true
    }
  ]
}

3. 创建 MQTT 配置

POST /api/mqtt

请求体:

{
  "broker": "tcp://127.0.0.1:1883",
  "client_id": "opencode-monitor",
  "username": "user",
  "password": "pass",
  "topic": "opencode/status",
  "enabled": true
}

字段	类型	必填	默认值	说明
broker	string	是	-	MQTT Broker 地址
client_id	string	否	opencode-monitor	客户端 ID
username	string	否	-	MQTT 用户名
password	string	否	-	MQTT 密码
topic	string	否	opencode/status	推送主题
enabled	boolean	否	true	是否启用

响应示例:

{
  "code": 0,
  "message": "创建成功",
  "data": {
    "id": 1,
    "broker": "tcp://127.0.0.1:1883",
    "client_id": "opencode-monitor",
    "username": "user",
    "password": "pass",
    "topic": "opencode/status",
    "enabled": true
  }
}

4. 获取单个 MQTT 配置

GET /api/mqtt/:id

路径参数: | 参数 | 类型 | 说明 | |------|------|------| | id | integer | 配置 ID |

响应示例:

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 1,
    "broker": "tcp://127.0.0.1:1883",
    "client_id": "opencode-monitor",
    "username": "user",
    "password": "pass",
    "topic": "opencode/status",
    "enabled": true
  }
}

5. 更新 MQTT 配置

PUT /api/mqtt/:id

路径参数: | 参数 | 类型 | 说明 | |------|------|------| | id | integer | 配置 ID |

请求体:

{
  "broker": "tcp://192.168.1.100:1883",
  "client_id": "my-monitor",
  "username": "user",
  "password": "pass",
  "topic": "my/topic",
  "enabled": false
}

响应示例:

{
  "code": 0,
  "message": "更新成功",
  "data": {
    "id": 1,
    "broker": "tcp://192.168.1.100:1883",
    "client_id": "my-monitor",
    "username": "user",
    "password": "pass",
    "topic": "my/topic",
    "enabled": false
  }
}

6. 删除 MQTT 配置

DELETE /api/mqtt/:id

路径参数: | 参数 | 类型 | 说明 | |------|------|------| | id | integer | 配置 ID |

响应示例:

{
  "code": 0,
  "message": "删除成功"
}

错误响应

所有错误响应格式:

{
  "code": -1,
  "message": "错误信息"
}

启动方式

# 方式1: 独立启动 API 服务
./bin/opencode-monitor serve --addr :8080

# 方式2: 监控时同时启动 API 服务
./bin/opencode-monitor monitor --ports 4096 --api-addr :8080

全局选项

以下选项适用于 monitor、serve、config 三个子命令：

选项	默认值	说明
--log-file	./logs	日志文件路径。默认 ./logs/monitor.log，按天自动轮转，同时输出到控制台和文件
--log-level	info	日志级别：debug、info、warn、error

日志示例

# 默认日志到 ./logs/monitor.log
./bin/opencode-monitor monitor --ports 4096

# 指定日志路径
./bin/opencode-monitor serve --log-file /var/log/monitor.log

# 开启 debug 日志
./bin/opencode-monitor monitor --scan 4096-4100 --log-level debug

日志文件轮转

日志按天自动轮转，跨天后旧文件自动重命名：

logs/
├── monitor.log           # 当天日志
├── monitor.log.2026-06-03  # 历史日志
└── monitor.log.2026-06-02  # 历史日志

CORS

API 已启用 CORS，支持跨域请求。

MQTT 推送说明

配置启用后，监控到状态变化时会自动推送到配置的 topic。消息格式为 JSON：

{
  "port": 4096,
  "status": "工作中",
  "code": "busy",
  "timestamp": "2026-06-03T14:30:00Z"
}

推送的状态类型

status	code	说明
空闲	idle	会话空闲
工作中	busy	会话工作中
重试中	retry	会话重试中
修改中	pending	会话修改中
思考中	reasoning	模型推理中
使用工具中	using_tool	AI 正在使用工具
等待中	pending	工具等待执行
运行中	running	工具执行中（可附带工具名，如 运行中: read）
工具执行完成	completed	工具执行完成（可附带工具名，如 工具执行完成: read）
会话完成	session_completed	会话执行完成
等待权限	permission	AI 向用户申请权限
错误	error	会话错误

WebSocket 实时状态

启动监控服务后，可以通过浏览器访问 http://localhost:8080 查看实时状态页面。

WebSocket 连接

ws://localhost:8080/ws

消息格式

WebSocket 推送的消息格式为 JSON：

{
  "port": 4096,
  "status": "工作中",
  "code": "busy",
  "timestamp": "2026-06-03T14:30:00Z"
}

使用示例

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('状态更新:', data);
};