用途

通过 OpenClaw 控制 Linear。创建 issue、梳理待办事项（backlog）、更新优先级、执行冲刺回顾（sprint review）——全部操作均可在你的 AI 助手中完成，无需切换浏览器标签页。

基于 Linear 的 GraphQL API，使用 curl 实现。无需安装 CLI 工具或 SDK。

适用场景

• 冲刺周期中途检查进度
• 根据会议纪要或对话内容快速创建 issue
• 梳理并重新排定待办事项（backlog）的优先级
• 站会（standup）前查询某个 issue 的当前状态
• 批量更新标签（labels）、负责人（assignees）或优先级（priorities）
• 跨项目或跨团队生成状态报告

不适用场景

• 复杂的 Figma / 设计评审（请使用浏览器端工具）
• GitHub PR 集成（请改用 github 技能）
• 将 Linear 与 Jira 或其他追踪系统同步（请直接调用 Linear API 编写脚本）

配置方法

1. 进入 Linear → Settings → API → Personal API keys
2. 创建一个 API 密钥（需具备 read + write 权限）
3. 将密钥添加至你的 OpenClaw 配置中：

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxx

验证密钥是否有效：

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"query": "{ viewer { name } }"}' | jq .

你应能看到自己的姓名返回。

命令

列出你当前打开的 issue

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "{ viewer { assignedIssues(filter: { state: { type: { nin: [\"completed\", \"cancelled\"] } } }) { nodes { id title priority state { name } team { name } } } } }"
  }' | jq '.data.viewer.assignedIssues.nodes'

获取某团队的 issue 列表

TEAM_KEY="ENG"  # 替换为你所在团队的 key

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    \"query\": \"{ team(key: \\\"$TEAM_KEY\\\") { issues(filter: { state: { type: { eq: \\\"started\\\" } } }) { nodes { id identifier title assignee { name } priority } } } }\" 
  }" | jq '.data.team.issues.nodes'

创建 issue

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "mutation IssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title } } }",
    "variables": {
      "input": {
        "teamId": "TEAM_ID_HERE",
        "title": "Issue title from OpenClaw",
        "description": "Created via OpenClaw linear skill.",
        "priority": 2
      }
    }
  }' | jq '.data.issueCreate'

优先级取值说明：0 = 无优先级，1 = 紧急（Urgent），2 = 高（High），3 = 中（Medium），4 = 低（Low）。

更新 issue

ISSUE_ID="ISSUE_ID_HERE"

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    \"query\": \"mutation { issueUpdate(id: \\\"$ISSUE_ID\\\", input: { priority: 1, stateId: \\\"STATE_ID\\\" }) { success issue { id title priority state { name } } } }\" 
  }" | jq '.data.issueUpdate'

按关键词搜索 issue

QUERY="authentication bug"

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    \"query\": \"{ issueSearch(query: \\\"$QUERY\\\") { nodes { id identifier title state { name } assignee { name } priority } } }\" 
  }" | jq '.data.issueSearch.nodes'

获取某团队当前冲刺周期（sprint）

TEAM_KEY="ENG"

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    \"query\": \"{ team(key: \\\"$TEAM_KEY\\\") { activeCycle { id name startsAt endsAt issues { nodes { id title state { name } estimate } } } } }\" 
  }" | jq '.data.team.activeCycle'

为 issue 添加评论

ISSUE_ID="ISSUE_ID_HERE"
COMMENT="LGTM — deploying to staging now."

curl -s -X POST https://api.linear.app/graphql 
  -H "Authorization: $LINEAR_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    \"query\": \"mutation { commentCreate(input: { issueId: \\\"$ISSUE_ID\\\", body: \\\"$COMMENT\\\" }) { success comment { id body } } }\" 
  }" | jq '.data.commentCreate'

示例

晨会准备：
“我有哪些优先级为 Urgent 或 High 的未关闭 Linear issue？”
→ 运行“列出你当前打开的 issue”查询，并按优先级 ≤ 2 过滤结果。

会后跟进：
“在 ENG 团队中创建一个 Linear issue：‘修复 auth token refresh 的竞态条件’，优先级设为 High”
→ 先查出 ENG 团队 ID，再运行 create mutation，传入标题及 priority=2。

冲刺回顾：
“展示当前 ENG 周期中所有已完成的 issue”
→ 获取 activeCycle，再筛选 state.type == "completed" 的 issue，并汇总其标题与预估工时（estimate）。

问题梳理（Triage）：
“将 ENG 团队中所有分配给 @alice 的 issue 状态改为 ‘In Progress’”
→ 先拉取相关 issue 列表，获取 “In Progress” 状态对应的 state ID，再对每个 issue 执行 issueUpdate。

注意事项

• 速率限制（Rate limits）：Linear API 每小时允许最多 1500 次请求。批量读取时建议缓存结果。
• ID 与 Key 的区别：团队（Team）可通过 key 查询（例如 "ENG"）；而 issue、state 和 cycle 必须使用 UUID。UUID 可通过列表类查询获取。
• GraphQL 自省（Introspection）：运行 { __schema { types { name } } } 可探索完整的 API Schema。
• Webhook：如需实时获取 issue 更新，请在 Linear → Settings → API → Webhooks 中配置 webhook，并配合 webhook-listener 技能使用。
• 分页（Pagination）：对于大型团队，请使用 first: N, after: cursor 方式进行分页。默认每页返回 50 条记录。