šŸ¦žOpenClaw Guide
Network

Proxy, SSL & Network Connection Issues

Troubleshoot network connectivity, webhook integrations, Copilot Proxy setup, API credential issues, and connection timeouts.

āš ļø The Problem

Users experience various network-related issues: connecting to external services like HubSpot that don't have native integrations, setting up Copilot Proxy for GitHub Copilot subscriptions, API key rejections and 401 errors, and understanding how to check versions and connection status.

šŸ” Why This Happens

OpenClaw has specific supported channels and integrations. Services without native support require webhook bridges or custom plugins. Common causes:

  1. No native integration exists - Services like HubSpot, WeChat, and others aren't built-in channels

  2. API keys stored incorrectly - Keys must be in the config file, not just environment variables (especially for sandboxed agents)

  3. Credential format issues - Some services need specific token formats or refresh mechanisms

  4. Webhook URL misconfiguration - External services can't reach local development instances without tunnels

  5. Copilot Proxy requires additional setup - Enabling the plugin is only step one

āœ… The Fix

Supported Native Integrations

OpenClaw has built-in support for:

  • Discord
  • Telegram
  • iMessage
  • Signal
  • Slack
  • WhatsApp
  • Microsoft Teams
  • Location services

For other services, you need webhooks or custom plugins.

Connect External Services via Webhooks (HubSpot, etc.)

For services without native integration, use the webhook endpoint:

Your webhook URL:

bash
https://YOUR_GATEWAY_URL/api/webhook/YOUR_BOT_ID

For local development, use ngrok or similar:

bash
ngrok http 3000# Then use: https://abc123.ngrok.io/api/webhook/YOUR_BOT_ID

Setting up HubSpot webhooks:

  1. Go to HubSpot ā†’ Settings ā†’ Integrations ā†’ Webhooks
  2. Create a new webhook subscription
  3. Enter your OpenClaw webhook URL
  4. Select the events you want to receive (contacts, deals, etc.)
  5. Save and test the connection

Webhook payload format OpenClaw expects:

json
{  "source": "hubspot",  "event": "contact.created",  "data": {    // Your event payload  }}

Set Up Copilot Proxy

The Copilot Proxy plugin lets you use your GitHub Copilot Pro subscription with OpenClaw.

Step 1: Enable the plugin

json5
{  plugins: {    copilotProxy: {      enabled: true    }  }}

Step 2: Authenticate with GitHub

Run the authentication flow:

bash
openclaw copilot auth

This opens a browser to authenticate with your GitHub account. The token is stored securely.

Step 3: Configure as a model provider

json5
{  models: {    providers: {      copilot: {        type: "copilot-proxy",        enabled: true      }    }  },  agents: {    defaults: {      model: "copilot/gpt-4"    }  }}

Common error:

bash
Copilot auth expired or invalid

Re-run openclaw copilot auth to refresh credentials.

Fix API Key / Credential Rejections

Error message:

bash
401 Invalid API key

Check 1: Key format

Ensure your API key doesn't have extra whitespace or quotes:

json5
// WRONG:{  apiKey: "  sk-abc123  "  // Has whitespace}// WRONG:{  apiKey: "'sk-abc123'"  // Has quotes inside}// CORRECT:{  apiKey: "sk-abc123"}

Check 2: Key location

For sandboxed agents, keys MUST be in the config file, not environment variables:

json5
// This works for sandboxed agents:{  tools: {    web: {      search: {        apiKey: "your-brave-api-key-here"      }    }  }}// This does NOT work in sandbox (env vars don't inherit):// BRAVE_API_KEY=xxx openclaw start

Check 3: Key refresh

Some services (like Moltbook) require periodic re-authentication:

bash
# Re-authenticate with Moltbookopenclaw moltbook auth# Check current auth statusopenclaw moltbook status

Error when credentials need refresh:

bash
Moltbook heartbeat check needs attention: the credentials file exists again, but Moltbook is rejecting the key.ā€¢ agents/status worked (shows claimed)ā€¢ agents/dm/check returned 401 Invalid API key

Check OpenClaw Version

Multiple ways to check your version:

bash
# Standard version checkopenclaw --versionopenclaw -vopenclaw -V# Full status including versionopenclaw status --all# If running from sourcepnpm openclaw --version

Example output:

bash
OpenClaw v1.2.3 (abc1234)Gateway: runningChannel: stable

Fix Connection Timeouts

If requests are timing out:

Check 1: Network connectivity from sandbox

json5
{  sandbox: {    docker: {      network: "bridge"  // Must not be "none"    }  }}

Check 2: DNS resolution

bash
# Test from inside the containerdocker exec -it openclaw-sandbox nslookup api.example.com

Check 3: Firewall/proxy settings

If you're behind a corporate firewall:

json5
{  network: {    proxy: "http://proxy.company.com:8080",    noProxy: ["localhost", "127.0.0.1", "*.internal.com"]  }}

WeChat Integration (Not Officially Supported)

WeChat is not officially supported due to its closed ecosystem. Community workarounds involve:

  1. Using WeChat's official API (requires business verification)
  2. Third-party bridges (security risks, ToS violations)
  3. Desktop automation (brittle, not recommended)

Check the Discord #integrations channel for community solutions.

Fix Log Flooding from Cron/Heartbeat

If logs are flooding with cron or heartbeat messages:

Check your cron schedule format:

json5
// WRONG - runs every millisecond:{  cron: {    schedule: "* * * * * *"  // 6-part = every second  }}// CORRECT - runs every minute:{  cron: {    schedule: "* * * * *"  // 5-part = every minute  }}// CORRECT - runs every hour:{  cron: {    schedule: "0 * * * *"  }}

Reduce heartbeat frequency:

json5
{  heartbeat: {    interval: 300000  // Every 5 minutes (in ms)  }}

Configure Reasoning/Thinking Visibility

To make /reasoning stream the default:

json5
{  agents: {    defaults: {      reasoning: "stream"  // Options: "off", "on", "stream"    }  }}
  • off - No reasoning visible
  • on - Reasoning shown after completion
  • stream - Reasoning streams in real-time (like /reasoning stream)

šŸ”„ Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator ā†’

šŸ“‹ Quick Commands

CommandDescription
openclaw --versionCheck the current OpenClaw version
openclaw status --allShow full status including version, gateway, and config
openclaw copilot authAuthenticate with GitHub for Copilot Proxy
openclaw moltbook authRe-authenticate with Moltbook when credentials expire
openclaw logs --followWatch logs in real-time to debug connection issues
ngrok http 3000Create a tunnel for webhook testing during local development

Related Issues

    šŸ“š You Might Also Like

    Blog

    HTTPS for OpenClaw: Setting Up a Reverse Proxy So Your Gateway Token Isn't Sent in the Clear

    Open your OpenClaw dashboard for the first time and look at the address bar: `http://`. Not `https://`. That \\"not secure\\" label your browser shows isn't cos

    Integration

    GitHub

    Connect OpenClaw to GitHub for AI-powered development workflows. Review PRs, manage issues, and automate code tasks with natural language.

    Guide

    How to Connect Gmail to Your AI Assistant (Complete Integration Guide)

    Turn Gmail into an AI-powered inbox. Summarize threads, draft replies, auto-categorize messages, and search your email with natural language.

    Use Case

    AI Assistant for CEOs

    More time on strategy. Less time on the information work that shouldn't need you.

    šŸ™ Your AI should run your business.

    Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

    Join Vibe Combinator ā†’