OpenClaw Linear Plugin

Receive Linear Agent Session webhooks and run OpenClaw agents on issues.

When a Linear issue is delegated to your agent app, this plugin:
1. Receives the webhook
2. Starts an OpenClaw agent session
3. Posts the agent's response back to Linear

Installation

``bash
npm install openclaw-linear-plugin
`

Prerequisites

$3

1. Go to Linear Settings → API → Applications
2. Create a new application with:
- Name: Your agent name (e.g., "DevBot")
- Webhook URL: https://your-gateway/plugins/linear/linear
- Enable Agent session events in webhook categories

$3

Complete the OAuth flow with these parameters:
`
https://linear.app/oauth/authorize?
client_id=YOUR_CLIENT_ID&
response_type=code&
scope=read,write,app:assignable,app:mentionable&
actor=app&
redirect_uri=YOUR_REDIRECT_URI
`

The actor=app parameter is required for agent functionality.

$3

The webhook URL must be publicly accessible. If using Tailscale, enable Funnel:

`bash
tailscale funnel 18789 # Replace with your gateway port
`

Configuration

Add to your openclaw.json:

`json
{
"plugins": {
"entries": {
"linear": {
"enabled": true,
"config": {
"devAgentId": "dev",
"linearWebhookSecret": "lin_wh_...",
"linearApiKey": "lin_oauth_...",
"defaultDir": "/path/to/repo",
"delegateOnCreate": true,
"startOnCreate": true
}
}
}
}
}
`

$3

| Option | Type | Description |
|--------|------|-------------|
| devAgentId | string | Agent ID to handle issues (default: "dev") |
| linearWebhookSecret | string | Webhook signing secret from Linear |
| linearApiKey | string | OAuth token from Linear app installation |
| defaultDir | string | Default repository directory |
| repoByTeam | object | Map team keys to repo directories |
| repoByProject | object | Map project keys to repo directories |
| delegateOnCreate | boolean | Auto-delegate issues to app (default: true) |
| startOnCreate | boolean | Move issues to "started" state (default: true) |
| notifyChannel | string | Optional: Channel for notifications (e.g., "discord") |
| notifyTo | string | Optional: Notification target (e.g., "channel:123456") |
| externalUrlBase | string | Optional: External session URL template |
| externalUrlLabel | string | Optional: Label for external URL link |

$3

Use placeholders for dynamic URLs:
`json
{
"externalUrlBase": "https://your-app.com/sessions/{session}",
"externalUrlLabel": "View Session"
}
`

Supports {session} and {issue} placeholders.

How It Works

1. Webhook Reception: Linear sends an AgentSessionEvent when an issue is delegated to your app
2. Initial Response: Plugin posts a "thinking" activity within 5 seconds
3. Agent Execution: OpenClaw agent runs with the issue context
4. Response Posting: Agent's reply is posted back to Linear as a response activity

$3

`
POST /plugins/linear/linear
`

The plugin verifies the Linear-Signature header when linearWebhookSecret is configured.

Troubleshooting

$3

- Check that your webhook URL is publicly accessible
- Verify linearApiKey has correct OAuth scopes
- Check OpenClaw logs for errors

$3

- Ensure linearWebhookSecret matches Linear's signing secret
- Check for clock skew (webhooks older than 60s are rejected)

$3

- Verify devAgentId matches an agent in your OpenClaw config
- Check that the agent has necessary tool permissions

Example Webhook Payload

`json
{
"action": "created",
"agentSession": {
"id": "session_abc123",
"issue": {
"id": "issue_xyz789",
"identifier": "ENG-123",
"title": "Fix login bug",
"url": "https://linear.app/team/issue/ENG-123"
}
},
"promptContext": "...",
"guidance": "Follow coding standards"
}
``

License

MIT © stumct