如何把 Linear 接入 Claude Managed Agentsmention 触发会话并把回复写回 issue 评论【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks如果你的 Linear workspace 里想让 Claude Managed AgentCMA像一个团队成员一样被 mention、然后自动在 issue 下回复评论可以参考 claude-cookbooks 仓库中managed_agents/linear目录下的桥接服务。这个项目实现了一个无状态 webhook 桥Linear issue 里的 mention 会触发 Linear 的AgentSessionEventwebhook桥用它创建一个带路由metadata的 CMA 会话并发送user.messageClaude 在 Anthropic 侧跑完后Anthropic 向桥推送session.status_idled事件桥再根据会话里的 metadata 把回复通过createAgentActivity写回 Linear issue 评论。整体链路如下来自 READMELinear mention ──▶ /linear-webhook ──▶ sessions.create ( metadata) ──▶ 200 │ Claude runs to idle on Anthropic infra │ /cma-webhook ◀── session.status_idled ◀──────────┘ │ └──▶ sessions.retrieve → read metadata → createAgentActivityCMA 会话的metadatalinear_session_id、linear_org_id就是全部路由状态桥本身不存任何业务数据。适用前提需要 Bun 运行时、一个公网可达的回调地址本地开发用 ngrok 或 cloudflared、Linear workspace 的 admin 权限OAuth 应用只能由 workspace 管理员创建以及一把 Anthropic API key。准备条件与代码结构进入模块目录并安装依赖cd managed_agents/linear bun installpackage.json 的依赖只有anthropic-ai/sdk^0.95.1README 明确要求 ≥ 0.95.1和linear/sdk^81.0.0。README 的 Quickstart 还提到可以运行claude启动 Claude CLI然后让它带着你完成配置——Claude 会读取 skill.md 按可工作的顺序走一遍。下面的手工路径和这条自动化路径做的事一致这里以手工路径为主线。各源码文件的分工文件清单见 README 的 Files 表文件职责setup/create-agent.ts一次性执行agents.createenvironments.createsrc/main.tsBun 服务入口与全部路由src/oauth.tsLinear OAuthactorapp与 token 存储src/agent.tssessions.create 带路由 metadata 的user.messagesrc/cma-webhook.tsbeta.webhooks.unwrap→ 按 metadata 过滤 → 发回复先起一个隧道拿到公网 URL后续所有回调地址都用它ngrok http 3000记下 ngrok 给出的https://...公网地址下面记作url。第一步一次性创建 Claude agent 和 environmentbun run setup该命令执行 setup/create-agent.ts调用 Anthropic SDK 创建一个名为linear-bridge-时间戳的 cloud environmentnetworking为unrestricted和一个名为Linear Assistant的 agent模型为claude-opus-4-7启用agent_toolset_20260401工具集system prompt 要求回复简短可执行、不要编造 issue ID、用户或项目名。执行成功后终端会打印Add to .env.local: CLAUDE_ENVIRONMENT_IDenv.id CLAUDE_AGENT_IDagent.id把这两个 ID 拷下来稍后写入.env.local。这一步只需要做一次。第二步创建 Linear OAuth 应用OAuth 应用只能由 workspace 管理员创建在linear.app/your-workspace/settings/api侧边栏进入Administration → API然后找到OAuth Applications区域点Create new见 skill.md。如果你不是公司 workspace 的 adminskill.md 建议先建一个免费的个人 workspace 做测试。创建时填写Developer URL必填但只是展示在授权页面上的链接任意真实的https://URL 即可Callback URLurl/oauth/callbackWebhook URLurl/linear-webhook订阅事件选择Agent session events记下client ID / client secret和webhook signing secret。这里有两个关键点直接决定后续能否跑通OAuth 授权时必须带scopeapp:assignable,app:mentionable和actorappsrc/oauth.ts 的handleOAuthAuthorize已包含。actorapp会在 Linear workspace 里创建一个app user这样 agent 才会出现在 选择器里个人LINEAR_API_KEY做不到这一点回复必须以 app 身份经 OAuth token 发出。src/agent.ts 在收到AgentSessionEvent后、创建 CMA 会话之前会先createAgentActivity发一条{type: thought, body: Thinking...}——因为 Linear 要求 10 秒内必须有第一条agentActivity否则该 session 会被标记为失败。第三步在 Anthropic Console 注册 CMA webhook在 Anthropic Console 的 Webhooks 页面注册端点URLurl/cma-webhook订阅事件session.status_idledsession.status_terminatedskill.md 建议只订阅需要的类型不要选 All events记下whsec_...开头的 signing key端点必须注册在与你的ANTHROPIC_API_KEY相同的 workspace。Anthropic webhook 是 workspace 级的如果 API key 属于 workspace A而端点注册在 workspace B会得到零投递且没有任何报错。检查 API key 所在 workspace 的方法是对照 API key 的 Workspace 列和 Console Webhooks 页的 workspace 选择器。反过来也要知道workspace webhook 会对该 workspace 里所有session 触发不只是你创建的。src/cma-webhook.ts 因此会先sessions.retrieve(id)检查metadata里是否有linear_session_id/linear_org_id不是自己的会话包括你的 key 读不到的其他 key 创建的 session会走 404/403 分支一律返回 204 丢弃。第四步填写 .env.local 并启动桥.env.local需要以下变量LINEAR_WEBHOOK_SIGNING_SECRET、ANTHROPIC_WEBHOOK_SIGNING_KEY、CLAUDE_AGENT_ID、CLAUDE_ENVIRONMENT_ID是 src/main.ts 启动时强制检查的缺失任意一个会打印FATAL: name is required并直接process.exit(1)LINEAR_CLIENT_ID、LINEAR_CLIENT_SECRET由 src/oauth.ts 的授权流程使用。BASE_URL未设置时默认http://localhost:PORTPORT默认 3000。cat .env.local EOF LINEAR_CLIENT_ID第二步复制的 client ID LINEAR_CLIENT_SECRET第二步复制的 client secret LINEAR_WEBHOOK_SIGNING_SECRET第二步复制的 webhook secret ANTHROPIC_WEBHOOK_SIGNING_KEY第三步复制的 whsec_... CLAUDE_AGENT_ID第一步打印的 agent ID CLAUDE_ENVIRONMENT_ID第一步打印的 environment ID BASE_URLngrok 公网 URL EOF其中ANTHROPIC_API_KEY由 SDK 从环境读取whsec_前缀的值填入ANTHROPIC_WEBHOOK_SIGNING_KEY。然后启动bun run dev启动后服务会打印路由信息可用于自检Bridge running at BASE_URL Install agent: BASE_URL/oauth/authorize Linear webhook: BASE_URL/linear-webhook CMA webhook: BASE_URL/cma-webhook服务在GET /上返回{status:ok}可以确认端口监听正常。第五步安装 agent 并触发 mention浏览器访问url/oauth/authorize该路由会把浏览器重定向到https://linear.app/oauth/authorize带response_typecode、scoperead,write,app:assignable,app:mentionable、actorapp。批准后回调url/oauth/callback完成 code 交换页面显示Agent installed in org name表示 token 已按 org 落盘到.linear-tokens.json生产环境 skill.md 建议换成正式的 secret store。在 Linear 的任意 issue 中 mention 这个 app user发一条消息。预期现象issue 下先出现 Thinking…这是 10 秒规则的第一条 thought 活动Claude 会话在 Anthropic 侧跑到 idle 后/cma-webhook收到session.status_idled桥从事件历史中提取所有agent.message文本以type: response的createAgentActivity写回评论。如果会话异常终止session.status_terminated桥会写回一条type: error、内容为 Agent session terminated unexpectedly. 的评论。排查与验证skill.md 给出了一张针对静默失败的排查表按现象定位现象检查项Thinking… 从未出现Linear webhook 没到达桥。检查 Linear 应用的 webhook URL以及 ngrok 是否还在运行有 Thinking… 但无回复查curl localhost:4040/api/requests/httpngrok 请求日志。没有 POST 到/cma-webhookAnthropic 侧 workspace 不匹配或端点没保存成功POST 到了但返回 401signing key 不一致回复内容为空sessions.events.list可能分页事件多时需要迭代完所有页还有两个容易踩的坑重试与幂等Anthropic 会用同一个顶层event.id重试失败的投递src/cma-webhook.ts 用内存seenEventIdsSet 去重处理完或决定忽略必须返回 2xx否则触发重试约 20 次连续失败会自动禁用端点。多实例部署时需把 Set 换成 Redis 或数据库。签名头文档写的是X-Webhook-Signature实际线路上传的是Webhook-Signature/Webhook-Id/Webhook-TimestampStandard Webhooks 规范。SDK 的webhooks.unwrap()已处理只有手工验签时才需要注意。限制与生产化说明skill.md 的 Production notes 列出的改动范围作为后续可选步骤非本文任务的必做项用真实部署Cloudflare Workers、Fly 等替换 ngrok其余不变内存seenEventIds换成 Redis/数据库以支持多实例幂等.linear-tokens.json文件换成正式 secret store把 Anthropic 端点的事件订阅收窄到只处理的事件类型如果 workspace 与他人共享考虑使用专用 workspace 避免无关 session 涌入。更多细节mental model、调试表可直接阅读 skill.md 与 README。【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考