OpenClaw线性插件

1. Install the plugin

openclaw plugins install @calltelemetry/openclaw-linear

Tunnel Setup (Cloudflare)

Linear delivers webhooks over the public internet. The gateway listens on localhost:18789 and needs a public HTTPS endpoint. A Cloudflare Tunnel is the recommended approach — no open ports, no TLS cert management, no static IP required.

How it works: cloudflared opens an outbound connection to Cloudflare's edge and keeps it alive. Cloudflare routes incoming HTTPS requests for your hostname back through the tunnel to localhost:18789. No inbound firewall rules needed.

Install cloudflared

```bash

Install as system service (recommended for production)

sudo cloudflared service install sudo systemctl enable --now cloudflared

To test without installing as a service:

Setup

{
  "notifications": {
    "targets": [
      { "channel": "discord", "target": "1471743433566715974" },
      { "channel": "telegram", "target": "-1003884997363" },
      { "channel": "slack", "target": "C0123456789", "accountId": "my-acct" }
    ],
    "events": {
      "auditing": false
    },
    "richFormat": true
  }
}

• targets — Where to send notifications (channel name + ID)
• events — Toggle specific events off (all on by default)
• richFormat — Set to true for Discord embeds with colors and Telegram HTML formatting

Quick Start

Tip: Claude Code is very good at setting this up for you. Install the plugin, install the Cloudflare CLI and authenticate (cloudflared tunnel login), then just ask Claude to configure the rest. Or run the guided setup wizard:

> openclaw openclaw-linear setup
> 

It walks through agent profiles, auth, webhook provisioning, and verification in one interactive flow.

Example Custom Prompts

worker:
  system: "You are a senior engineer. Write clean, tested code."
  task: |
    Issue: {{identifier}} — {{title}}

    {{description}}

    Workspace: {{worktreePath}}

    Implement this issue. Write tests. Commit your work.

audit:
  system: "You are a strict code auditor."

rework:
  addendum: |
    PREVIOUS AUDIT FAILED. Fix these gaps:
    {{gaps}}

Configure the tunnel

Create /etc/cloudflared/config.yml (system-wide) or ~/.cloudflared/config.yml (user):

tunnel: <TUNNEL_ID>
credentials-file: /home/<user>/.cloudflared/<TUNNEL_ID>.json

ingress:
  - hostname: linear.yourdomain.com
    service: http://localhost:18789
  - service: http_status:404    # catch-all, reject unmatched requests

The ingress rule routes all traffic for your hostname to the gateway on localhost. The catch-all http_status:404 rejects requests for any other hostname.

Phase 1: Planning (optional)

Trigger: Comment "let's plan the features" on a project issue.

For larger work, the planner breaks a project into issues before any code is written. It enters interview mode — asking questions, creating issues with user stories and acceptance criteria, and building a dependency graph in real time.

The planner proactively asks for: - User stories — "As a [role], I want [feature] so that [benefit]" - Acceptance criteria — Given/When/Then format - UAT test scenarios — How to manually verify the feature

What you'll see in Linear:

I've created 3 issues: - PROJ-2: Build search API endpoint (3 pts, blocks PROJ-3) - PROJ-3: Search results page (2 pts, blocked by PROJ-2) - PROJ-4: Autocomplete suggestions (1 pt, independent) Does that cover it? Should the autocomplete call a separate endpoint or share the search API?

When you say "looks good", the planner validates the plan (descriptions, estimates, no circular deps) and sends it to a different AI model for a cross-model review:

After approval, issues are dispatched automatically in dependency order — up to 3 in parallel.

📊 Search Feature: 2/3 complete

Configuration

Add settings under the plugin entry in openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-linear": {
        "config": {
          "defaultAgentId": "coder",
          "maxReworkAttempts": 2,
          "enableAudit": true
        }
      }
    }
  }
}

Plugin Settings

Environment Variables

Step 1.5: Sync labels to Linear (optional)

If you plan to use labels (Method B below) to tag issues, run this to create the repo:xxx labels automatically:

openclaw openclaw-linear repos sync

This reads your repos config and creates matching labels (repo:api, repo:frontend, etc.) in every Linear team. To preview without creating anything:

openclaw openclaw-linear repos check

The check command also validates your repo paths — it'll warn you if a path doesn't exist, isn't a git repo, or is a submodule (which won't work with multi-repo dispatch).

Quick Reference

---

Gateway API

For programmatic access, the plugin registers these RPC methods:

---

`linear_issues` — Native Linear API

Agents call linear_issues with typed JSON parameters. The tool wraps the Linear GraphQL API directly and handles all name-to-ID resolution automatically.

Sub-issues: Use action="create" with parentIssueId to create sub-issues under an existing issue. The new issue inherits teamId and projectId from its parent automatically. Only orchestrators on triaged issues have create access — workers and auditors cannot create issues.

Linear API & Hook Architecture

This section documents every interaction between the plugin and the Linear GraphQL API, the webhook event routing, the hook lifecycle, and the dispatch pipeline internals.

GraphQL API Layer

All Linear API calls go through LinearAgentApi (src/api/linear-api.ts), which wraps https://api.linear.app/graphql with automatic token refresh, retry resilience, and 401 recovery.

Token resolution (resolveLinearToken) checks three sources in priority order:

1. pluginConfig.accessToken — static config
2. Auth profile store (~/.openclaw/auth-profiles.json) — OAuth tokens with auto-refresh
3. LINEAR_ACCESS_TOKEN / LINEAR_API_KEY environment variable

OAuth tokens get a Bearer prefix; personal API keys do not. Tokens are refreshed 60 seconds before expiry via refreshLinearToken(), and the refreshed credentials are persisted back to the auth profile store.

API methods by category:

Core Pipeline

• Auto-triage — New issues get story point estimates, labels, and priority within seconds. Read-only mode — no side effects.
• Worker → Auditor pipeline — Assign an issue and a worker implements it in an isolated git worktree. An independent auditor verifies the work. The worker cannot self-certify — the audit is hard-enforced in plugin code.
• Complexity-tier dispatch — The plugin assesses each issue and picks the right model. Simple typo? Haiku. Multi-service refactor? Opus. Saves cost and latency without manual intervention.
• Automatic rework — Failed audits feed gaps back to the worker as context. Retries up to N times before escalating. No human needed until the agents are stuck.

Step 1: Tell the plugin where your repos live

Add a repos map to your plugin config in openclaw.json. The key is a short name you pick, the value is the absolute path to that repo on disk:

{
  "plugins": {
    "entries": {
      "openclaw-linear": {
        "config": {
          "repos": {
            "api": "/home/claw/repos/api",
            "frontend": "/home/claw/repos/frontend",
            "shared": "/home/claw/repos/shared-libs"
          }
        }
      }
    }
  }
}

Restart the gateway after saving: systemctl --user restart openclaw-gateway