hope-client（希望客户）

hope-client

Hope Server Max API 客户端技能。用于发起对 Hope Server Max 服务端的 API 请求。

环境变量配置

OpenClaw 自动加载 ~/.openclaw/.env 文件中的环境变量：

# ~/.openclaw/.env
HOPE_API_KEY=hope-openclaw-apikey-2026-0411
HOPE_HOST=hope05
HOPE_PORT=8088

加载优先级（官方文档）：

1. 进程已存在的环境变量（不会被覆盖）
2. CWD .env 文件
3. ~/.openclaw/.env 文件

技能脚本通过环境变量读取配置：

认证方式

所有请求必须携带 X-OpenClaw-Key 请求头：

# 使用环境变量
curl -H "X-OpenClaw-Key: $HOPE_API_KEY" \
  http://$HOPE_HOST:$HOPE_PORT/system/channel/list

从本地通过 SSH 调用：

sshpass -p 'hope' ssh $HOPE_HOST \
  "curl -s -H 'X-OpenClaw-Key: $HOPE_API_KEY' http://127.0.0.1:$HOPE_PORT/system/channel/list"

API 接口文档

1. 频道管理 (Channel)

1.1 查询频道列表

GET /system/channel/list

查询参数：

• channelName - 频道名称（可选）
• channelType - 频道类型：bili、youtube、xigua（可选）
• channelOffOn - 启用状态：on、off（可选）
• pageNum - 页码（默认 1）
• pageSize - 每页数量（默认 10）

响应示例：

{
  "total": 88,
  "rows": [
    {
      "channelId": 267,
      "channelName": "CopyCat-bili",
      "channelType": "bili",
      "channelOffOn": "on",
      "cookieEnable": "true",
      "engineId": 3,
      "engineName": "hope03"
    }
  ],
  "code": 200,
  "msg": "查询成功"
}

1.2 获取所有频道名称

GET /system/channel/listAllNames

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": ["CopyCat-bili", "CopyCat-youtube", ...]
}

1.3 搜索频道名称

GET /system/channel/searchNames?channelName=Copy

查询参数：

• channelName - 搜索关键词（可选，最多返回 5 条）

1.4 获取频道详情

GET /system/channel/{channelId}

1.5 频道统计信息

GET /system/channel/statistics

1.6 刷新频道 Cookie

POST /system/channel/refresh/{channelId}

2. 上传实例 (Upload Instance)

2.1 查询上传实例列表

GET /system/instance/list

查询参数：

• channelName - 频道名称（可选）
• status - 状态：0=成功, 1=失败, 2=执行中, 3=排队（可选）
• engineName - 引擎名称（可选）
• videoName - 视频名称（可选）
• pageNum - 页码
• pageSize - 每页数量

响应示例：

{
  "total": 150,
  "rows": [
    {
      "instanceId": "abc123",
      "channelName": "CopyCat-bili",
      "videoName": "测试视频",
      "videoPath": "/path/to/video.mp4",
      "status": "0",
      "uploadLog": "上传成功",
      "createTime": "2026-04-16 10:00:00"
    }
  ],
  "code": 200
}

2.2 获取上传实例详情

GET /system/instance/{instanceId}

2.3 查询上传趋势数据

GET /system/instance/queryTrend

查询参数：

• channelName - 频道名称（可选）
• beginTime - 开始时间（可选）
• endTime - 结束时间（可选）

2.4 查询失败排行列表

GET /system/instance/failList

2.5 查询失败日志

POST /system/instance/queryFailLog

请求体：

{
  "engineName": "hope02",
  "videoPath": "/path/to/video.mp4"
}

3. 下载实例 (Download Instance)

3.1 查询下载实例列表

GET /system/downloadInstance/list

查询参数：

• downloadId - 下载 ID（可选）
• videoName - 视频名称（可选）
• cleanFlag - 清理状态：0=已清理, 1=手动清理, 2=未清理（可选）
• pageNum - 页码
• pageSize - 每页数量

3.2 获取下载实例详情

GET /system/downloadInstance/{pkInstanceId}

3.3 查询待上传视频列表

GET /system/downloadInstance/pending

查询参数：

• downloadId - 下载 ID（可选）
• limit - 返回数量限制（可选）

响应示例：

{
  "total": 500,
  "rows": [
    {
      "pkInstanceId": "md5hash...",
      "videoName": "待上传视频",
      "videoPath": "/path/to/video.mp4",
      "channelName": "CopyCat-bili",
      "cleanFlag": 2
    }
  ],
  "code": 200
}

3.4 统计待上传视频数量

GET /system/downloadInstance/pending/count

查询参数：

• downloadId - 下载 ID（可选）

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": 500
}

3.5 查询下载趋势数据

GET /system/downloadInstance/trend

3.6 更新清理状态

PUT /system/downloadInstance/clean/{pkInstanceIds}

4. 账户管理 (Account)

4.1 查询账户列表

GET /system/account/list

查询参数：

• accName - 账户名称（可选）
• accPhone - 手机号（可选）
• accDue - 到期时间（可选）

4.2 获取账户详情

GET /system/account/{accId}

5. 引擎管理 (Engine)

5.1 查询引擎列表

GET /system/engineInfo/list

响应示例：

{
  "total": 6,
  "rows": [
    {
      "engineId": 1,
      "engineName": "hope01",
      "engineIp": "192.168.31.54",
      "engineType": "youtube"
    }
  ],
  "code": 200
}

5.2 获取所有引擎信息

GET /system/engineInfo/listAll

5.3 获取引擎详情

GET /system/engineInfo/{engineId}

快速调用函数

技能提供以下快捷调用函数（写入 scripts/api_client.sh）：

基础调用

# 调用 API 的基础函数
hope_api() {
  local endpoint="$1"
  local params="${2:-}"
  
  sshpass -p 'hope' ssh hope@hope05 \
    "curl -s -H 'X-OpenClaw-Key: hope-openclaw-apikey-2026-0411' \
     'http://127.0.0.1:8088${endpoint}?${params}'"
}

常用快捷命令

# 查询频道列表
hope_channel_list() {
  hope_api "/system/channel/list" "pageSize=100"
}

# 查询待上传视频数量
hope_pending_count() {
  hope_api "/system/downloadInstance/pending/count"
}

# 查询待上传视频列表
hope_pending_list() {
  hope_api "/system/downloadInstance/pending" "limit=20"
}

# 查询上传实例列表
hope_upload_list() {
  hope_api "/system/instance/list" "pageSize=50"
}

# 查询引擎列表
hope_engine_list() {
  hope_api "/system/engineInfo/listAll"
}

使用场景

场景 1：检查待上传视频数量

hope_pending_count
# 输出：{"code":200,"data":500}

场景 2：查询某频道的上传记录

hope_api "/system/instance/list" "channelName=CopyCat-bili&pageSize=20"

场景 3：查询失败的上传任务

hope_api "/system/instance/list" "status=1&pageSize=50"

场景 4：查询今日下载入库数量

hope_api "/system/downloadInstance/trend" "beginTime=2026-04-16"

状态码说明

upload_instance.status

download_instance.clean_flag

注意事项

1. 网络访问：hope05 是内网服务器（192.168.31.167），需通过 SSH 或内网访问
2. 认证必须：所有请求必须携带 X-OpenClaw-Key 请求头
3. 分页参数：列表接口默认 pageNum=1, pageSize=10
4. 时间格式：时间参数格式为 yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd