Troubleshooting

Fix common issues with ClawLink integrations and agent connectivity

Start every debugging session with Request Logs. Go to your dashboard and open the logs to see exactly which integration was called, what action was attempted, and any error message returned. Most issues can be diagnosed in under a minute from the logs alone.

Common issues

Connection shows 'Needs reconnect'

A Needs reconnect status usually means the provider credentials expired, were revoked, or need fresh consent.

To fix this:

1. Go to Dashboard > Connections

   Open your dashboard and navigate to Connections.

2. Expand the affected row

   Find the affected app and expand its connection row.

3. Run the hosted reconnect flow

   Click Reconnect and finish the provider flow in the popup.

ClawLink tools are missing in OpenClaw

Copy this into your OpenClaw chat and the agent will fix it for you:

My ClawLink plugin is installed and enabled but its tools are missing in this chat.
Please do the following and report back:

1. Run `openclaw plugins install @useclawlink/openclaw-plugin` then `openclaw gateway restart`.
2. Print the gateway startup log line that lists loaded plugins. Confirm both `tools` and `clawlink-plugin` appear in that list.
3. If `tools` is missing, open `~/.openclaw/openclaw.json`. If a `plugins.allow` array is set, add `"tools"` and `"clawlink-plugin"` to it, save, and run `openclaw gateway restart` again.
4. Once `tools` is loaded, start a fresh chat and call `clawlink_get_pairing_status`. If pairing is not complete, call `clawlink_begin_pairing` and walk me through approving the device in the browser.

On managed OpenClaw deployments you cannot edit the gateway config yourself — ask your OpenClaw admin to enable the bundled tools plugin and reload the gateway, then run the steps above.

Why this works: ClawLink registers its tools through OpenClaw’s bundled tools host plugin. If tools is not loaded, ClawLink’s tools cannot reach agent sessions even though the plugin is installed. The most common second cause is that the current chat started before the plugin was installed, so its tool catalog is stale and a fresh chat is needed.

API calls are failing

If your agent is making requests but they’re failing, check the Request Logs for details.

To diagnose this:

1. Go to your dashboard and open Request Logs
2. Find the failed request—the log shows the integration, the action attempted, and the error message returned
3. Use the error message to identify whether the issue is with your credentials, the request itself, or the third-party service

Common causes include invalid parameters, permissions issues with the connected account, or the third-party service being temporarily unavailable.

Pairing link expired or approval did not finish

Pairing links are short lived. If the browser page says the session expired, or OpenClaw never finishes after you approved it, start a fresh pairing flow.

To fix this:

1. Start pairing again from OpenClaw

   Ask OpenClaw to set up ClawLink or start pairing again.

2. Approve the new browser URL

   Open the new pairing URL, sign in if needed, and click Approve this device.

3. Return to OpenClaw

   After approval, go back to OpenClaw so the plugin can finish the local save step.

Rate limit errors

Rate limit errors mean the third-party API (not ClawLink) has throttled requests from your account. This happens when too many calls are made in a short window.

ClawLink automatically retries rate-limited requests with exponential backoff—so occasional rate limits resolve themselves. If failures persist, your agent is making requests faster than the third-party API allows.

To resolve persistent rate limiting:

• Slow down how frequently your agent triggers the affected integration
• Check the third-party service’s rate limit documentation to understand the limits for your account tier
• Consider upgrading your account with the third-party service if you need higher throughput

OAuth token expired (Gmail, Google Sheets, etc.)

Some integrations—including Gmail, Google Sheets, and Google Calendar—use OAuth tokens that expire over time. When a token expires, the integration will stop working until you refresh it.

To fix this:

1. Go to Dashboard > Connections

   Open your dashboard and navigate to Connections.

2. Reconnect to get a fresh token

   Expand the affected row and click Reconnect. This runs the hosted provider flow again and refreshes the token.

Manual API key setup is not working

Manual key entry is a fallback path. If it fails, the simplest fix is usually to switch back to browser pairing.

Check the following:

• Make sure the key starts with cllk_live_...
• Confirm you copied the raw key when it was first shown after creation
• Revoke old keys you no longer trust and create a fresh one if needed
• If possible, remove the manual key and run browser pairing instead

Requests not appearing in logs

If your agent is running but you don’t see requests in the logs, try the following:

1. Refresh the logs page—there can be a short delay before new entries appear
2. Confirm the device is paired—if OpenClaw is not authenticated to ClawLink, requests never reach tool execution
3. Verify the app is actually connected—an unconnected provider cannot produce tool execution rows
4. Check the local credential—if the device credential was revoked, requests are rejected before they are logged

If requests still do not appear after a few minutes, run pairing again and make sure the app is connected in Connections.