# How to Connect ClickUp to OpenClaw

- Tool: OpenClaw
- Difficulty: Intermediate
- Time required: 20 minutes
- Last updated: March 2026

## TL;DR

To connect OpenClaw to ClickUp, store your CLICKUP_API_KEY in OpenClaw's config and configure direct HTTP calls to the ClickUp REST API. This is a Direct API integration. Once set up, OpenClaw can create and update tasks, manage spaces and lists, read workspace data, and integrate ClickUp task management into broader automation workflows through ClickUp's comprehensive REST API.

## Integrate OpenClaw With ClickUp's Full API Surface

ClickUp is one of the most feature-dense project management platforms available, and its REST API v2 exposes nearly all of that functionality programmatically. The hierarchy — workspace > spaces > folders > lists > tasks — gives teams a flexible organizational structure, and every level is accessible via the API. The OpenClaw Direct API integration makes it straightforward to build automation workflows that read from and write to ClickUp as part of broader AI-assisted processes.

ClickUp's API strength is in its custom field support. Unlike simpler task managers, ClickUp lets teams define arbitrary custom fields on tasks — text, numbers, dropdowns, dates, checkboxes, ratings, and more. The API exposes full read/write access to custom fields, which means OpenClaw can create tasks with all the fields your team uses, not just the standard title/description/due date combination. This is particularly valuable for teams that have standardized their task templates with required custom fields.

Authentication in ClickUp uses a personal API token that is associated with your ClickUp user account. It grants access to all workspaces, spaces, and tasks your account can access — appropriate for server-to-server automation where you want OpenClaw to act on your behalf across your full ClickUp workspace.

## Before you start

- OpenClaw installed and running (see openclaw.ai for installation instructions)
- A ClickUp account with at least one workspace, space, and list
- Access to ClickUp Personal Settings > Apps to generate a personal API token
- Your ClickUp workspace ID, team ID, and target list ID (found via the API or ClickUp URLs)
- Basic familiarity with REST APIs and JSON

## Step-by-step guide

### 1. Generate a ClickUp Personal API Token

ClickUp personal API tokens authenticate requests as your user account. Unlike OAuth tokens, personal tokens do not expire and grant access to all workspaces your account belongs to.

Log in to ClickUp and go to your profile avatar in the bottom-left corner > Settings > Apps > API Token. If you do not see a token, click 'Generate' to create one. Copy the token — it is a long alphanumeric string.

ClickUp also supports OAuth apps for multi-user integrations, but for OpenClaw automation on your own workspaces, a personal API token is the correct approach. Store it in OpenClaw as CLICKUP_API_KEY.

```
# Set your ClickUp API token in OpenClaw config
clawhub config set CLICKUP_API_KEY pk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Verify it is set
clawhub config get CLICKUP_API_KEY

# Test the connection — should return your ClickUp user info
curl -H "Authorization: pk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  "https://api.clickup.com/api/v2/user"
```

**Expected result:** CLICKUP_API_KEY set in OpenClaw config. The test curl call returns a JSON object with your ClickUp user information including your user ID.

### 2. Find Your Workspace and List IDs

ClickUp's API hierarchy uses numeric IDs to identify workspaces (also called teams), spaces, folders, and lists. You need these IDs to make targeted API calls.

**Team/Workspace ID:** Call the `/team` endpoint to list all workspaces your account belongs to. Each workspace has a numeric ID.

**Space ID:** Call `/team/{team_id}/space` to list spaces in a workspace.

**List ID:** You can find list IDs in the ClickUp URL when viewing a list: `https://app.clickup.com/{team_id}/v/li/{LIST_ID}`. Or call `/space/{space_id}/list` to list all lists in a space.

Note the IDs for the workspaces and lists you want to access — store them in your OpenClaw config for easy reference.

```
# Get workspace/team IDs
curl -H "Authorization: pk_YOUR_TOKEN" \
  "https://api.clickup.com/api/v2/team"

# Get spaces in a workspace
curl -H "Authorization: pk_YOUR_TOKEN" \
  "https://api.clickup.com/api/v2/team/YOUR_TEAM_ID/space"

# Get lists in a space
curl -H "Authorization: pk_YOUR_TOKEN" \
  "https://api.clickup.com/api/v2/space/YOUR_SPACE_ID/list"

# Find list ID from URL:
# https://app.clickup.com/TEAM_ID/v/li/LIST_ID
```

**Expected result:** You have numeric IDs for your workspace, the spaces you want to access, and the lists where you will create or read tasks.

### 3. Configure ClickUp Integration in OpenClaw

Add the ClickUp integration configuration to your OpenClaw config file. This stores your team ID and frequently-used list IDs under descriptive names so workflows reference them by name rather than numeric ID.

CLICKUP_API_KEY is read automatically from your environment config — do not repeat it in the YAML file. The config sets default values that workflows use when specific IDs are not provided explicitly.

```
# ~/.openclaw/config.yaml
integrations:
  clickup:
    team_id: "YOUR_TEAM_ID"         # Your ClickUp workspace/team ID
    default_assignee: "YOUR_USER_ID"  # Your ClickUp user ID (from /user response)
    # Named list references
    lists:
      bug_reports: "LIST_ID_1"
      feature_requests: "LIST_ID_2"
      content_pipeline: "LIST_ID_3"
      task_inbox: "LIST_ID_4"
    # Default task settings
    defaults:
      priority: 3           # 1=Urgent, 2=High, 3=Normal, 4=Low
      status: "Open"        # Default status for new tasks
```

**Expected result:** Config file saved with ClickUp integration settings. `clawhub reload` completes without errors.

### 4. Create and Read ClickUp Tasks

Test task creation and reading. ClickUp's task creation endpoint is POST `/list/{list_id}/task` with a JSON body containing the task fields. Required fields: `name`. Optional fields include `description`, `assignees` (array of user IDs), `status`, `priority`, `due_date` (Unix timestamp in milliseconds), `time_estimate`, `tags`, and `custom_fields`.

For reading tasks, GET `/list/{list_id}/task` returns all tasks in a list with extensive filtering options: by assignee, status, due date range, priority, tags, and custom field values. The response is paginated — check the `last_page` field to determine if more pages exist.

ClickUp's search API at `/team/{team_id}/task` allows cross-list and cross-space task searches, which is more powerful than list-specific queries for finding tasks by criteria across your entire workspace.

```
# Create a task in a list
curl -X POST \
  -H "Authorization: pk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.clickup.com/api/v2/list/LIST_ID/task" \
  -d '{
    "name": "Review onboarding email sequence",
    "description": "Check for outdated links and update copy for Q2",
    "assignees": [USER_ID],
    "priority": 2,
    "due_date": 1745280000000,
    "tags": ["content", "email"]
  }'

# Read tasks from a list (incomplete only)
curl -H "Authorization: pk_YOUR_TOKEN" \
  "https://api.clickup.com/api/v2/list/LIST_ID/task?include_closed=false"

# Search tasks across workspace
curl -H "Authorization: pk_YOUR_TOKEN" \
  "https://api.clickup.com/api/v2/team/TEAM_ID/task?assignees[]=USER_ID&due_date_lt=1746489600000"
```

**Expected result:** POST creates a new task visible in the ClickUp list. GET returns a JSON array of tasks with all their fields, assignees, and statuses.

### 5. Update Tasks, Set Status, and Use Custom Fields

Task updates use PUT `/task/{task_id}` with a JSON body containing only the fields to change. Status updates are done the same way — set `status` to the name of the target status as defined in your ClickUp list's status configuration.

Custom fields require their UUID (not their display name) in API calls. Get custom field UUIDs by calling GET `/list/{list_id}/field` — this returns all custom fields configured for that list with their IDs, types, and allowed values. Then include custom field values in task creation and update calls using the `custom_fields` array.

RapidDev recommends caching the list of custom field IDs locally rather than fetching them on every API call — custom field configurations rarely change and fetching them repeatedly wastes API quota and adds latency to task creation workflows.

```
# Update a task's status and priority
curl -X PUT \
  -H "Authorization: pk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.clickup.com/api/v2/task/TASK_ID" \
  -d '{
    "status": "In Progress",
    "priority": 1,
    "due_date": 1746057600000
  }'

# Get custom field definitions for a list
curl -H "Authorization: pk_YOUR_TOKEN" \
  "https://api.clickup.com/api/v2/list/LIST_ID/field"

# Create a task with custom field values
curl -X POST \
  -H "Authorization: pk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.clickup.com/api/v2/list/LIST_ID/task" \
  -d '{
    "name": "Bug: Login timeout",
    "priority": 1,
    "custom_fields": [
      {"id": "CUSTOM_FIELD_UUID", "value": "High"},
      {"id": "ANOTHER_FIELD_UUID", "value": "Chrome"}
    ]
  }'
```

**Expected result:** Task status updated in ClickUp and visible in the list view. Tasks with custom fields created correctly show the custom field values in the task detail view.

## Best practices

- Cache workspace, space, and list IDs in your OpenClaw config rather than fetching them dynamically on every workflow run — these IDs are stable and rarely change.
- Fetch custom field UUIDs once and store them in your config — custom field IDs are static and fetching them on every task creation call adds unnecessary API overhead.
- Use descriptive list aliases in your config (`bug_reports`, `feature_requests`) rather than raw numeric IDs to make workflow configurations readable and maintainable.
- Respect ClickUp's rate limits: the API allows 100 requests per minute on free plans and higher limits on paid plans. Add delays between bulk operations to avoid 429 errors.
- Set the `priority` field using the numeric values (1-4) rather than string labels — numeric values are consistent across API versions, while status string names can vary by workspace configuration.
- For cross-space task queries, use the `/team/{team_id}/task` search endpoint with filters rather than querying each list individually — it is more efficient and supports complex filtering.
- Always verify API responses contain expected fields before using them in subsequent steps — ClickUp's API responses include many optional fields that may be null or missing depending on task configuration.

## Use cases

### Automated Task Creation with Custom Fields

Create ClickUp tasks with full field population including custom fields — translating structured data from other systems into properly formatted ClickUp tasks with priorities, assignees, custom field values, and tags.

Prompt example:

```
Configure OpenClaw to create a ClickUp task in my 'Bug Reports' list with priority Urgent, assigned to the QA team, with custom fields for 'Severity' set to 'High' and 'Browser' set to 'Chrome'.
```

### Cross-Space Task Aggregation

Query tasks across multiple ClickUp spaces to generate a unified view — finding all overdue tasks, tasks assigned to a specific person across all projects, or tasks with a specific tag regardless of which space they live in.

Prompt example:

```
Read all incomplete ClickUp tasks assigned to me across all my workspaces that are due this week. Sort them by priority and return as a formatted list.
```

### Workflow State Machine

Build a workflow where task status in ClickUp drives what OpenClaw does next — read tasks in a specific status, process them, and move them to the next status on completion. This turns ClickUp into an external state machine for OpenClaw workflows.

Prompt example:

```
Build an OpenClaw integration that reads all ClickUp tasks with status 'Ready for Review' from my 'Content' list, processes each one, and updates the status to 'In Review' when done.
```

## Troubleshooting

### API returns 'OAUTH_027: Authorization header not found'

Cause: CLICKUP_API_KEY is not being sent in the Authorization header, is not set in OpenClaw's config, or the header name is wrong (ClickUp uses `Authorization` not `Authorization: Bearer`).

Solution: Verify the key is set with `clawhub config get CLICKUP_API_KEY`. ClickUp's API uses the token directly in the Authorization header without the 'Bearer' prefix. Ensure your HTTP call sends `Authorization: pk_your_token` not `Authorization: Bearer pk_your_token`.

```
clawhub config set CLICKUP_API_KEY pk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
clawhub reload
```

### Task creation returns 'OAUTH_MEMBER_003: You do not have access to this resource'

Cause: The list ID used in the task creation request does not belong to a workspace your API token has access to, or the list ID is incorrect.

Solution: Verify the list ID by navigating to the list in ClickUp and checking the URL. Confirm the list belongs to the same workspace as your API token's account. Run GET `/team` to list workspaces your token can access and verify the list is within one of them.

```
# Verify accessible team IDs
curl -H "Authorization: pk_YOUR_TOKEN" "https://api.clickup.com/api/v2/team"

# List all lists in a space to confirm IDs
curl -H "Authorization: pk_YOUR_TOKEN" "https://api.clickup.com/api/v2/space/SPACE_ID/list"
```

### Status update fails with 'STATUS_008: Invalid status'

Cause: The status name in the update request does not match any status defined for that list. ClickUp statuses are per-list and case-sensitive.

Solution: Fetch the valid statuses for the list with GET `/list/{list_id}` and check the `statuses` array. Use exactly the status names returned, including correct capitalization.

```
# Get valid statuses for a list
curl -H "Authorization: pk_YOUR_TOKEN" "https://api.clickup.com/api/v2/list/LIST_ID"
```

### clawhub config set CLICKUP_API_KEY is not persisting after restart

Cause: The config may not be saving correctly if `~/.openclaw/.env` has conflicting values or if the config file is read-only.

Solution: Check `~/.openclaw/.env` for a CLICKUP_API_KEY entry and update it directly if present. Verify the OpenClaw config directory is writable: `ls -la ~/.openclaw/`.

```
# Check and directly edit .env if needed
cat ~/.openclaw/.env | grep CLICKUP
```

## Frequently asked questions

### How do I set up ClickUp integration in OpenClaw?

Go to ClickUp Settings > Apps > API Token and copy your personal token. Set it in OpenClaw with `clawhub config set CLICKUP_API_KEY pk_your-token`. Find your team ID by calling GET `/team` with the token. Add your team ID and list IDs to `~/.openclaw/config.yaml` under `integrations.clickup`. Test with a GET request to `/user` to verify authentication.

### What is the CLICKUP_API_KEY for OpenClaw?

It is a ClickUp personal API token found in your ClickUp Settings (profile icon > Settings > Apps > API Token). It starts with `pk_` followed by a long alphanumeric string. Unlike OAuth tokens, personal API tokens do not expire. The token authenticates all API calls as your ClickUp user account.

### How do I find my ClickUp list ID for the OpenClaw integration?

Open the ClickUp list in a browser. The list ID appears in the URL: `https://app.clickup.com/{team_id}/v/li/{LIST_ID}`. Alternatively, call the ClickUp API at `/space/{space_id}/list` with your API token to list all lists and their IDs programmatically.

### Why is my ClickUp task status update failing?

ClickUp status names are per-list and case-sensitive. The status string in your API call must exactly match a status defined for that specific list. Fetch valid statuses with GET `/list/{list_id}` and check the `statuses` array. Use the exact name strings returned, including correct capitalization.

### Does RapidDev offer help with ClickUp OpenClaw integration?

Yes — RapidDev can assist with configuring ClickUp automation in OpenClaw, particularly for complex use cases involving custom fields, multi-space task management, and integrating ClickUp as a state machine in larger workflows. Reach out to RapidDev for configuration support beyond what this guide covers.

### Can OpenClaw work with ClickUp custom fields?

Yes — ClickUp's API v2 supports full read and write access to custom fields. You need the custom field UUID (not the display name) for API calls. Fetch field UUIDs with GET `/list/{list_id}/field` and include them in the `custom_fields` array when creating or updating tasks. Custom field types include text, number, dropdown, date, checkbox, and more.

---

Source: https://www.rapidevelopers.com/openclaw-integrations/clickup
© RapidDev — https://www.rapidevelopers.com/openclaw-integrations/clickup