RingClaw

English

简体中文

English

简体中文

Appearance

Getting Started ​

Quick Start ​

bash
# One-line install (macOS/Linux)
curl -sSL https://raw.githubusercontent.com/ringclaw/ringclaw/main/install.sh | sh

# One-line install (Windows PowerShell)
irm https://raw.githubusercontent.com/ringclaw/ringclaw/main/install.ps1 | iex

# Interactive setup (prompts for bot token, chat IDs, etc.)
ringclaw setup

# Start
ringclaw start

All configuration lives in ~/.ringclaw/config.json. Environment variables such as RC_BOT_TOKEN are no longer consulted — run ringclaw setup or edit the file directly. See Configuration.

That's it. On first start, RingClaw will:

  1. Connect to RingCentral via the Bot App's WebSocket
  2. Auto-detect installed AI agents (Claude, Codex, Gemini, etc.)
  3. Save config to ~/.ringclaw/config.json
  4. Start receiving and replying to messages

RingCentral Setup ​

TIP

After creating your apps, run ringclaw setup for an interactive wizard that collects credentials, validates them, and saves the config file.

Step 1: Create a Bot App (Required) ​

  1. Go to RingCentral Developer Console and sign in

    RingCentral Developer Console login

  2. Click Register App → select Bot Add-in

    Register App

    Select Bot Add-in

  3. Configure the app:

    • Security → Application Scopes: check Read Accounts, Read Messages, TeamMessaging, WebSockets Subscription, WebSockets
    • Access: Private (only your own account)

    Application Scopes

  4. Click Create

  5. Go to the Bot tab → click Install to install the bot to your account

  6. Copy the Bot Token shown on the Bot tab

    Copy Bot Token

Step 2: Find Chat IDs ​

  1. Open the conversation between you and your Bot in RingCentral

  2. Click More → Copy conversation link

  3. The number after /messages/ is the Chat ID (e.g. 1234567890 from https://app.ringcentral.com/l/messages/1234567890)

    Copy conversation link to get Chat ID

Step 3: Create a Private App (Optional) ​

A Private App (REST API with JWT) enables additional features:

  • Summarize conversations from other chats
  • Cross-chat actions (read messages, create tasks in other chats)

  1. In the Developer Console, click Register App → select REST API App (most common)

    Select REST API App

  2. Configure the app:

    • Auth: JWT auth flow
    • Security → Application Scopes: check Read Accounts, Read Messages, TeamMessaging, WebSockets Subscription, WebSockets
    • Access: Private

  3. Click Create — you'll get a Client ID and Client Secret

  4. Go to Credentials tab → JWT Credentials → click Create JWT Token

    Create JWT Token

  5. Copy the JWT token

    Copy JWT Token

Interactive Setup ​

bash
ringclaw setup

The wizard will:

  • Prompt for Bot Token (required)
  • Prompt for chat IDs to monitor
  • Optionally configure Private App credentials (Client ID, Secret, JWT Token)
  • Validate credentials against the RingCentral API
  • Save everything to ~/.ringclaw/config.json

Install Channels ​

bash
curl -sSL .../install.sh | sh                 # stable (latest tag)
curl -sSL .../install.sh | sh -s -- beta      # beta (latest main build)
curl -sSL .../install.sh | sh -s -- alpha feature/my-branch  # alpha (specific branch)

Switch channels via CLI:

bash
ringclaw update                                    # update to latest stable
ringclaw update --channel beta                     # switch to beta channel
ringclaw update --channel alpha --branch feature/foo  # switch to alpha branch

macOS Note

The installer and ringclaw update automatically clear Gatekeeper quarantine attributes (com.apple.quarantine, com.apple.provenance), so the binary won't be killed after download.

Other Install Methods ​

bash
# Via Go
go install github.com/ringclaw/ringclaw@latest

# Via Docker (mount ~/.ringclaw to share config.json with the container)
docker run -it -v ~/.ringclaw:/root/.ringclaw \
  ghcr.io/ringclaw/ringclaw start