How to Connect Linear to OpenClaw: AI Project Management

Linear is fast. That is the whole point of it. Keyboard shortcuts, sub-second search, cycles that map to how your team ships. The problem is that Linear still requires you to be inside Linear. You cannot create an issue from a Telegram message, get a cycle progress report during your morning commute, or have an AI flag blockers before standup.

OpenClaw fixes that gap. By writing a custom skill that talks to Linear’s GraphQL API, your OpenClaw agent becomes a conversational interface to your issue tracker. You ask “what is blocking the v2 release?” and the agent queries Linear, filters by label and state, and gives you an answer in seconds. This guide covers the full setup: API key, skill file, GraphQL queries, and four automation recipes worth building.

---

Before You Start

You need three things before connecting Linear to OpenClaw:

1. OpenClaw installed and running. If you have not set this up yet, follow our OpenClaw setup guide. That guide covers installation, workspace configuration, memory, and model selection.

2. A Linear account with API key permissions. Admins and permitted members can create personal API keys. If you are on a restricted member role, ask your workspace admin to enable API access for your account under Settings > Account > Security & Access.

3. curl and jq available on your system. The skill uses curl for GraphQL requests and jq to parse JSON responses. Both come pre-installed on most Linux distributions and macOS. On Ubuntu, run sudo apt install jq if it is missing.

If you want OpenClaw running 24/7 without keeping your laptop open, deploy it on a VPS. Our Hostinger deployment guide walks through that setup.

---

Step 1: Create a Linear Personal API Key

Linear’s public API is built on GraphQL, and it uses the same system that powers the Linear app itself. Authentication is straightforward: a personal API key in the request header.

Choosing the Right Scopes

Linear lets you restrict each API key to specific permission levels and teams. Here is what you need for a standard OpenClaw integration:

Scope	Required	What It Enables
Read	Yes	Query issues, cycles, projects, teams, labels, and users
Write	Recommended	Create and update issues, change states, assign labels
Create issues	Optional	Narrower alternative to full Write access
Create comments	Optional	Post comments on issues from the agent
Admin	No	Not needed. Do not enable this unless you have a specific reason.

Start with Read and Write. If your team prefers tighter scoping, use Read plus Create issues and Create comments instead of full Write. You can also restrict the key to specific teams in your workspace, which is useful if your agent should only interact with the engineering team and not the design team.

Generate the Key

1. Open Linear and navigate to Settings (press G then S, or click your profile icon and select Settings)
2. Go to Account > Security & Access > Personal API Keys
3. Click New API Key
4. Name it something descriptive: openclaw-linear-integration
5. Select the scopes from the table above
6. Optionally restrict to specific teams
7. Click Create and copy the key immediately. Linear only shows it once.

Store the key in a .env file outside your OpenClaw workspace:

# ~/.env or ~/openclaw/.env
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Do not paste the key directly into your skill file or any workspace document. Environment variables keep secrets out of your agent’s memory and context window.

---

Step 2: Write the OpenClaw Linear Skill

OpenClaw skills are Markdown files that teach your agent how to use external tools. The skill file defines when to activate, what API calls to make, and what rules to follow. For Linear, the skill wraps GraphQL queries into patterns the agent can adapt based on your natural language requests.

Create the Skill Directory

mkdir -p ~/.openclaw/workspace/skills/linear

Write the SKILL.md File

Create ~/.openclaw/workspace/skills/linear/SKILL.md with this content:

---
name: linear
description: Query and manage Linear issues, cycles, and projects via the GraphQL API. Supports issue CRUD, cycle tracking, blocker detection, and filtered searches.
tools:
  - shell
---

# Linear Project Management Skill

## Authentication

Use the environment variable `LINEAR_API_KEY` for all requests.
Endpoint: `https://api.linear.app/graphql`
Header: `Authorization: $LINEAR_API_KEY`

All queries use this base curl pattern:

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

## Available Operations

### List My Issues

Fetch issues assigned to the authenticated user:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ viewer { assignedIssues(first: 25, orderBy: updatedAt) { nodes { identifier title state { name } priority assignee { name } dueDate } } } }"}' \
  https://api.linear.app/graphql | jq '.data.viewer.assignedIssues.nodes'

### Search Issues by Text

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ searchIssues(term: \"SEARCH_TERM\", first: 10) { nodes { identifier title state { name } team { name } assignee { name } } } }"}' \
  https://api.linear.app/graphql | jq '.data.searchIssues.nodes'

### Get Issues by Team and State

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

### Get Issues by Label

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ issues(filter: { labels: { name: { eq: \"LABEL_NAME\" } } }, first: 50) { nodes { identifier title state { name } priority assignee { name } } } }"}' \
  https://api.linear.app/graphql | jq '.data.issues.nodes'

### Create an Issue

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "mutation { issueCreate(input: { title: \"ISSUE_TITLE\", description: \"ISSUE_DESCRIPTION\", teamId: \"TEAM_ID\", priority: PRIORITY_NUMBER }) { success issue { identifier title url } } }"}' \
  https://api.linear.app/graphql | jq '.data.issueCreate'

Priority levels: 0 = No priority, 1 = Urgent, 2 = High, 3 = Normal, 4 = Low.

### Update an Issue

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

### Get Active Cycle for a Team

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ team(id: \"TEAM_ID\") { activeCycle { id name startsAt endsAt progress completedIssueCountAfterStart issueCountAfterStart issues { nodes { identifier title state { name type } priority assignee { name } } } } } }"}' \
  https://api.linear.app/graphql | jq '.data.team.activeCycle'

### List Teams

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

### List Workflow States for a Team

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ team(id: \"TEAM_ID\") { states { nodes { id name type position } } } }"}' \
  https://api.linear.app/graphql | jq '.data.team.states.nodes'

## Rules

- Always confirm before creating or updating issues. Show the user the details and ask for confirmation.
- When creating issues, ask for the team first. Use the List Teams query to find the team ID.
- For issue updates, show the current state before and proposed change before executing.
- Priority is numeric: 1 = Urgent, 2 = High, 3 = Normal, 4 = Low, 0 = None.
- Never log the API key in responses or memory.
- When a user mentions a specific issue (like "ENG-123"), query by identifier first.

How the Skill Works

The frontmatter tells OpenClaw when to activate the Linear skill and that it needs the shell tool for running curl commands.

The operations section provides templated GraphQL queries. When you ask “what is the status of ENG-42?”, the agent reads the search pattern, substitutes your issue identifier, runs the query, and formats the JSON response into a readable answer.

The rules section prevents the agent from creating or modifying issues without your explicit confirmation. This matters more than you might think. An agent can easily create three duplicate issues from a single conversation if the phrasing is ambiguous. The confirmation step is a cheap safeguard that prevents expensive cleanup.

---

Step 3: Test the Connection

Restart OpenClaw so it picks up the new skill:

openclaw gateway restart

Open your Telegram chat (or whichever channel you use) and run through these tests:

Authentication test:

“List all my Linear teams”

The agent should return your team names and keys. If this works, the API key is valid and scoped correctly.

Read test:

“Show me my open issues in Linear”

The agent queries your assigned issues and returns titles, states, and priorities.

Search test:

“Find Linear issues mentioning ‘authentication’”

The agent uses the search query and returns matching issues across teams.

Write test:

“Create a Linear issue in the Engineering team: Fix broken OAuth redirect, priority high”

The agent should ask you to confirm the details before executing the mutation. If it creates the issue without asking, strengthen the confirmation rule in your SKILL.md.

Test	What to Check
List teams	Teams returned with IDs and keys
My issues	Issues show correct states and priorities
Search	Results match the search term across teams
Create issue	Agent asks for confirmation before creating
Cycle status	Active cycle returned with progress percentage

If any test fails, check the troubleshooting section below.

---

Step 4: Set Up Webhooks for Real-Time Events

The basic setup means you ask the agent to check Linear. Webhooks reverse that: Linear tells OpenClaw when something happens, and the agent reacts without being prompted.

This is the difference between “check my issues every morning” and “alert me when someone assigns me a P1 bug.”

Create a Webhook via the Linear API

Linear supports webhook creation through its GraphQL API. You can create one using curl with your API key:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "mutation { webhookCreate(input: { url: \"https://your-server/hooks/agent\", resourceTypes: [\"Issue\", \"Comment\", \"Cycle\"], allPublicTeams: true }) { success webhook { id enabled } } }"}' \
  https://api.linear.app/graphql

Linear sends a Linear-Signature header with each webhook payload, computed as an HMAC-SHA256 hash of the request body. Verify this in your webhook handler to reject forged requests.

Alternatively, create the webhook from Linear’s UI: go to Settings > API > Webhooks > New Webhook, paste your OpenClaw endpoint URL, and select the event types you want.

Wire It to an OpenClaw Agent

In your OpenClaw config (~/.openclaw/openclaw.json), add a hook mapping for Linear events:

{
  "hooks": {
    "enabled": true,
    "token": "your-webhook-secret",
    "path": "/hooks",
    "allowedAgentIds": ["linear-watcher"],
    "mappings": {
      "linear-issue": {
        "agentId": "linear-watcher",
        "channel": "telegram",
        "deliver": true,
        "message": "A Linear event just occurred: {{text}}. Check the issue details using the Linear skill, assess priority, and send me a summary if this needs attention."
      }
    }
  }
}

Restart the gateway after updating the config. Now when a high-priority issue is created in Linear, the agent fetches the details, evaluates whether it needs your immediate attention, and delivers a summary to Telegram.

---

Four Automations Worth Building

Once the connection works, these are the four automations that deliver the most value for startup teams.

Auto-Create Issues from Conversations

The most natural workflow. Someone mentions a bug in your Telegram group, and instead of context-switching to Linear, you tell the agent:

“Create a Linear issue from that bug report: login redirect fails on Safari, priority high, label it as bug, Engineering team”

The agent runs the issueCreate mutation with the details and confirms the issue URL. No browser tab, no form fields, no copy-pasting.

When issue creation is this frictionless, reporting rates tend to go up significantly, not because there are more bugs, but because the barrier to filing them drops to near zero. Feature requests that would otherwise die in Slack threads start appearing in the backlog.

Daily Standup Prep

Add this to your heartbeat.md to run every morning before standup:

## Linear Standup Prep (runs at 8:30 AM)
Query my assigned issues in Linear that are in "In Progress" or "In Review" state.
For each issue, check if it has been updated in the last 24 hours.
Group them into: actively worked on, stale (no updates), and blocked (has "blocker" label).
Send the summary to Telegram as a formatted standup report.

The agent delivers a message at 8:30 AM with three sections: what you worked on, what has gone quiet, and what is blocked. Copy the summary into your standup meeting or just read it from your phone. It takes the “what did I do yesterday?” guesswork out of the equation.

Cycle Progress Reports

Linear’s cycle progress is calculated as (completed points + 0.25 * in-progress points) / total points. Your agent can query this and deliver a human-readable status:

“How is the current sprint going for the Engineering team?”

The agent fetches the active cycle, calculates completion percentage, lists remaining issues by priority, and flags anything that might slip. Schedule this as a Friday afternoon heartbeat to get a weekly summary without opening Linear.

For teams that report to non-technical stakeholders, this is gold. The CEO gets a Telegram message saying “Sprint 23 is 72% complete, 3 issues remaining, 1 blocked on design review” instead of asking you to pull up a dashboard.

Blocker Detection

The most underrated automation. Configure a heartbeat that runs twice daily:

## Blocker Detection (runs at 9:00 AM and 2:00 PM)
Query all issues in the current cycle that have the "blocker" or "blocked" label,
or that have been in the same state for more than 3 days without an update.
If any are found, send me a summary with the issue identifier, title, current state,
assignee, and how long it has been stuck. Flag issues with no assignee separately.

Blockers are expensive because they compound. An issue stuck for two days often means another issue gets stuck tomorrow. This automation catches stalled work before it cascades. Identifying blockers 1-2 days earlier than manual standup reviews allows can meaningfully reduce average cycle time.

---

Troubleshooting Common Problems

Symptom	Likely Cause	Fix
401 Unauthorized	API key is invalid or expired	Generate a new key in Linear Settings > Account > Security & Access
Empty results for team queries	API key restricted to different teams	Edit the key’s team access or create a new key with the correct teams
”Cannot query field” errors	GraphQL schema mismatch	Check field names against the Linear API explorer. Field names are camelCase.
Agent creates issues without confirming	Weak confirmation rule in SKILL.md	Add a stronger instruction: “You MUST show details and wait for user approval before any mutation.”
Webhook events not arriving	URL unreachable or signature mismatch	Verify your server is publicly accessible and the webhook secret matches between Linear and OpenClaw config
Rate limiting (429 errors)	Too many API calls in a short window	Batch queries using GraphQL’s nested structure. One query can fetch issues, assignees, and labels in a single request.
Cycle data returns null	No active cycle for the team	The team might be between cycles. Query cycles(first: 1, orderBy: createdAt) to get the most recent one instead.

If you hit GraphQL errors frequently, use the Linear API Explorer on Apollo Studio to test queries interactively before adding them to your skill file. It supports schema introspection and auto-completion.

---

Frequently Asked Questions

Does OpenClaw need admin access to my Linear workspace?

No. A personal API key with Read and Write scopes is sufficient for issue management, cycle tracking, and search. Admin access is only needed for workspace-level settings like creating teams or managing members. Keep the key scoped to what the agent needs.

Can I restrict the agent to a single Linear team?

Yes. When creating a personal API key, Linear lets you limit access to specific teams. If your workspace has Engineering, Design, and Marketing teams but you only want the agent interacting with Engineering, select just that team during key creation. The agent’s queries will return empty results for other teams.

What happens if my Linear API key gets revoked?

The agent’s Linear-related commands start failing with 401 errors. OpenClaw itself keeps running; it just cannot complete Linear tasks. Generate a new API key in Settings, update the LINEAR_API_KEY value in your .env file, and restart the OpenClaw gateway. The agent picks up the new key immediately.

Can OpenClaw move issues between states automatically?

It can, using the issueUpdate mutation with a new stateId. Whether it should is a different question. Automatic state changes bypass the visual workflow your team relies on in Linear’s board view. We recommend having the agent suggest state changes and wait for confirmation rather than executing them silently. If you do want automatic transitions, restrict them to low-risk moves like Triage to Backlog.

Is my Linear data sent to OpenAI or Anthropic?

It depends on your model configuration. If OpenClaw uses a cloud LLM, the issue titles, descriptions, and query results are sent to that provider for processing. If you use a local model through Ollama or llama.cpp, everything stays on your machine. For teams with sensitive project data, run a local model for Linear queries and a cloud model for general tasks. OpenClaw’s multi-model configuration supports this split.

How is this different from Linear’s built-in AI features?

Linear’s native AI handles triage suggestions, auto-labeling, and duplicate detection within the Linear app. OpenClaw adds a conversational layer on top: you interact with your issues from Telegram, WhatsApp, or any other channel. You also get scheduled automations (standup prep, blocker detection) that Linear’s AI does not support natively. Think of Linear AI as intelligence inside the app; OpenClaw as intelligence outside the app.

Can I use this with Linear’s SDK instead of curl?

Yes. If your OpenClaw instance runs in a Node.js environment, you can replace the curl commands in the skill file with @linear/sdk calls. The SDK provides typed methods like linearClient.issues() and linearClient.createIssue(). The trade-off is that you need Node.js on your server and the SDK installed. For most deployments, curl with jq is simpler and has no dependencies.

---

Key Takeaways

• Create a Linear personal API key with Read and Write scopes, restricted to the teams your agent needs. Store it in a .env file, not in workspace files.
• The OpenClaw skill uses curl to send GraphQL queries to https://api.linear.app/graphql. The skill file defines query templates the agent adapts to your natural language requests.
• Test the connection with read operations (list teams, search issues) before enabling write operations (create issues, update states).
• Set up Linear webhooks to make the integration event-driven. The agent reacts to new issues and state changes without polling.
• The four highest-value automations are conversational issue creation, daily standup prep, cycle progress reports, and automated blocker detection.
• For sensitive projects, use a local model for Linear queries to keep issue data off third-party servers.