name: hardcover
description: 通过 GraphQL API 查询 Hardcover.app 的阅读清单与图书数据。当用户提及 Hardcover、询问其阅读清单/书库、查询阅读进度、搜索图书/作者/系列，或提及"正在阅读"、"想读"、"已读书籍"时触发。也可用于将阅读数据同步至其他系统（如 Obsidian）或追踪阅读目标。
homepage: https://hardcover.app
metadata:
{
"openclaw":
{
"emoji": "📚",
"requires": { "env": ["HARDCOVER_API_TOKEN"] },
},
}

Hardcover GraphQL API

查询您的阅读书库、图书元数据，并搜索 Hardcover 目录。

配置

• 环境变量： HARDCOVER_API_TOKEN（从 https://hardcover.app/settings 获取）
• 端点： https://api.hardcover.app/v1/graphql
• 速率限制： 60 次请求/分钟，30 秒超时，最大查询深度为 3

认证

所有查询均需在请求头中包含 Authorization: Bearer {token}（从设置页面获取令牌，并添加 Bearer 前缀）：

curl -X POST https://api.hardcover.app/v1/graphql \
  -H "Authorization: Bearer $HARDCOVER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { me { id username } }"}'

工作流程

1. 先获取用户 ID — 多数查询需要此信息：
   graphql query { me { id username } }

2. 按状态查询 — 使用 status_id 筛选：
   - 1 = 想读
   - 2 = 正在阅读
   - 3 = 已读
   - 4 = 暂停
   - 5 = 未完成

3. 分页处理大量结果 — 使用 limit/offset，并添加 distinct_on: book_id

常用查询

获取正在阅读的书籍及进度

query {
  me {
    user_books(where: { status_id: { _eq: 2 } }) {
      user_book_reads { progress_pages }
      book {
        title
        pages
        image { url }
        contributions { author { name } }
      }
    }
  }
}

按状态查询书库

query ($userId: Int!, $status: Int!) {
  user_books(
    where: { user_id: { _eq: $userId }, status_id: { _eq: $status } }
    limit: 25
    offset: 0
    distinct_on: book_id
  ) {
    book {
      id
      title
      pages
      image { url }
      contributions { author { name } }
    }
  }
}

搜索图书/作者/系列

query ($q: String!, $type: String!) {
  search(query: $q, query_type: $type, per_page: 10, page: 1) {
    results
  }
}

query_type 可选值：Book、Author、Series、Character、List、Publisher、User

按书名查询图书详情

query {
  editions(where: { title: { _eq: "Oathbringer" } }) {
    title
    pages
    isbn_13
    edition_format
    publisher { name }
    book {
      slug
      contributions { author { name } }
    }
  }
}

限制

• 仅支持只读操作（暂不支持数据变更）
• 不支持文本搜索运算符（如 _like、_ilike、_regex）
• 访问范围限于：您的数据、公开数据、已关注用户的数据
• 令牌有效期为 1 年

实体参考

有关图书、版本、作者、系列、用户书籍、活动、清单、目标及其他实体的详细字段文档，请参阅 references/entities.md。

响应代码