Installing the OpenClaw Rating API Edge Go SDK – Senior Engineer Tutorial

1. Introduction

The current AI‑agent hype is driving enterprises to embed intelligent feedback loops into their products. Whether you’re building a conversational assistant, a recommendation engine, or a content‑moderation pipeline, you need a reliable way to capture and score user interactions. OpenClaw provides a high‑performance Rating API that sits at the edge, delivering sub‑millisecond latency and built‑in fraud protection.

This tutorial walks senior engineers through the end‑to‑end workflow: installing the Go SDK, authenticating securely, configuring token‑bucket rate‑limiting, and issuing sample rating requests. We’ll also glimpse how OpenClaw can be hosted on UBOS for seamless scaling, and we’ll reference Moltbook as a real‑world integration that showcases the SDK in action.

2. Prerequisites

• Go 1.20+ installed (go version should return 1.20 or later).
• Access to an OpenClaw tenant with a valid API key or OAuth client.
• Basic familiarity with Go modules and context handling.

Make sure your GOPATH and PATH are correctly set, and that you have a terminal window ready for go commands.

3. Installing the OpenClaw Rating API Edge Go SDK

The SDK is distributed as a Go module. Run the following command from your project root:

go get github.com/openclaw/rating-api-edge-go/v2

After the download completes, verify the module is listed in your go.mod file:

cat go.mod | grep openclaw

You should see an entry similar to:

github.com/openclaw/rating-api-edge-go/v2 v2.3.1

Now you can import the SDK in your Go source files:

import (
    "github.com/openclaw/rating-api-edge-go/v2/client"
    "github.com/openclaw/rating-api-edge-go/v2/rating"
)

4. Authentication

OpenClaw supports two authentication flows:

• API Key: Simple static token passed in the Authorization header.
• OAuth 2.0 Client Credentials: Dynamic token acquisition via the token endpoint.

4.1 Using an API Key

package main

import (
    "context"
    "log"
    "github.com/openclaw/rating-api-edge-go/v2/client"
)

func main() {
    ctx := context.Background()
    cfg := client.Config{
        BaseURL:   "https://api.openclaw.io/v1",
        APIKey:    "YOUR_STATIC_API_KEY", // <-- keep this secret!
        Timeout:   10 * time.Second,
    }

    c, err := client.New(cfg)
    if err != nil {
        log.Fatalf("SDK init failed: %v", err)
    }

    // c is now ready for rating calls
    _ = c
}

4.2 OAuth 2.0 Client Credentials

When you need short‑lived tokens, use the built‑in OAuth helper:

package main

import (
    "context"
    "log"
    "time"

    "github.com/openclaw/rating-api-edge-go/v2/client"
    "golang.org/x/oauth2/clientcredentials"
)

func main() {
    ctx := context.Background()

    // OAuth2 config
    oauthCfg := clientcredentials.Config{
        ClientID:     "YOUR_CLIENT_ID",
        ClientSecret: "YOUR_CLIENT_SECRET",
        TokenURL:     "https://auth.openclaw.io/oauth2/token",
        Scopes:       []string{"rating.write"},
    }

    // Obtain a token source
    tokenSrc := oauthCfg.TokenSource(ctx)

    cfg := client.Config{
        BaseURL:   "https://api.openclaw.io/v1",
        TokenSrc:  tokenSrc,
        Timeout:   10 * time.Second,
    }

    c, err := client.New(cfg)
    if err != nil {
        log.Fatalf("SDK init failed: %v", err)
    }

    // c now automatically refreshes tokens
    _ = c
}

Best practice: Store APIKey, ClientID, and ClientSecret in a secret manager (e.g., Vault, AWS Secrets Manager) rather than hard‑coding them.

5. Token‑Bucket Rate‑Limiting

Why token‑bucket? It smooths burst traffic while guaranteeing a maximum request rate, which is essential for edge APIs that enforce strict QPS limits.

5.1 Concept Overview

A token bucket holds a configurable number of tokens (capacity). Each request consumes one token. Tokens are replenished at a fixed refillRate (tokens per second). If the bucket is empty, the SDK blocks or returns an error, preventing over‑consumption.

5.2 Configuring the SDK

The Go SDK ships with a middleware that you can enable via the RateLimiter option:

package main

import (
    "context"
    "log"
    "time"

    "github.com/openclaw/rating-api-edge-go/v2/client"
    "github.com/openclaw/rating-api-edge-go/v2/middleware/ratelimit"
)

func main() {
    ctx := context.Background()

    // Rate limiter: 100 QPS burst up to 200 requests
    limiter := ratelimit.NewTokenBucket(
        ratelimit.WithCapacity(200),      // max burst
        ratelimit.WithRefillRate(100),    // tokens per second
    )

    cfg := client.Config{
        BaseURL:    "https://api.openclaw.io/v1",
        APIKey:     "YOUR_STATIC_API_KEY",
        Timeout:    10 * time.Second,
        RateLimiter: limiter,
    }

    c, err := client.New(cfg)
    if err != nil {
        log.Fatalf("SDK init failed: %v", err)
    }

    // Example request (see next section)
    _ = c
}

5.3 Handling Rate‑Limit Errors

When the bucket is empty, the middleware returns ratelimit.ErrRateLimited. You can decide to retry with exponential back‑off:

if errors.Is(err, ratelimit.ErrRateLimited) {
    // Simple back‑off
    time.Sleep(time.Second * 2)
    // retry logic...
}

6. Making Sample Rating Requests

A rating request consists of a UserID, a ItemID, and a numeric Score (0‑5). Optional metadata can be attached for analytics.

6.1 Request Structure

type RatingRequest struct {
    UserID   string            `json:"user_id"`
    ItemID   string            `json:"item_id"`
    Score    int               `json:"score"` // 0‑5
    Context  map[string]string `json:"context,omitempty"`
}

6.2 Full Example with Error Handling

package main

import (
    "context"
    "log"
    "time"

    "github.com/openclaw/rating-api-edge-go/v2/client"
    "github.com/openclaw/rating-api-edge-go/v2/rating"
    "github.com/openclaw/rating-api-edge-go/v2/middleware/ratelimit"
)

func main() {
    ctx := context.Background()

    // 1️⃣ Initialise rate limiter (100 QPS, burst 150)
    limiter := ratelimit.NewTokenBucket(
        ratelimit.WithCapacity(150),
        ratelimit.WithRefillRate(100),
    )

    // 2️⃣ Build SDK config (using API key for brevity)
    cfg := client.Config{
        BaseURL:    "https://api.openclaw.io/v1",
        APIKey:     "YOUR_STATIC_API_KEY",
        Timeout:    8 * time.Second,
        RateLimiter: limiter,
    }

    // 3️⃣ Create client
    sdk, err := client.New(cfg)
    if err != nil {
        log.Fatalf("Failed to create OpenClaw client: %v", err)
    }

    // 4️⃣ Prepare rating payload
    req := rating.RatingRequest{
        UserID: "user-12345",
        ItemID: "article-9876",
        Score:  4,
        Context: map[string]string{
            "source": "mobile-app",
            "session_id": "sess-abcde",
        },
    }

    // 5️⃣ Execute request with retry on rate‑limit
    var resp *rating.RatingResponse
    for attempts := 0; attempts < 3; attempts++ {
        resp, err = sdk.Rating.Submit(ctx, req)
        if err == nil {
            break
        }
        if errors.Is(err, ratelimit.ErrRateLimited) {
            backoff := time.Duration(attempts+1) * time.Second
            log.Printf("Rate limited, backing off %v...", backoff)
            time.Sleep(backoff)
            continue
        }
        log.Fatalf("Rating request failed: %v", err)
    }

    // 6️⃣ Process response
    log.Printf("Rating accepted, ID: %s, processed_at: %s", resp.RatingID, resp.ProcessedAt)
}

Key takeaways:

• Always pass a context.Context to enable cancellation and timeout propagation.
• Leverage the built‑in token‑bucket to stay within OpenClaw’s QPS limits.
• Log the RatingID for downstream reconciliation.

7. Best‑Practice Tips

8. Integration Showcase: Moltbook

Moltbook, a collaborative note‑taking platform, recently integrated the OpenClaw Rating API to capture real‑time sentiment on shared documents. By embedding the Go SDK into its backend microservice, Moltbook can:

• Collect a 0‑5 rating each time a user bookmarks a paragraph.
• Enrich the rating payload with document_id and section_hash for fine‑grained analytics.
• Throttle bursts during collaborative editing sessions using the token‑bucket, keeping latency under 30 ms.

The result is a feedback loop that powers Moltbook’s AI‑driven recommendation engine, surfacing the most helpful sections to new readers. This real‑world case demonstrates how the SDK scales from a single‑node dev environment to a multi‑region production deployment.

9. Conclusion

You now have a complete, production‑ready recipe for working with the OpenClaw Rating API Edge Go SDK:

1. Install the SDK via go get.
2. Choose the authentication method that matches your security posture.
3. Configure a token‑bucket rate limiter to respect OpenClaw’s QPS guarantees.
4. Send rating requests with robust error handling and observability.

As AI agents continue to dominate product roadmaps, integrating a fast, reliable feedback channel like OpenClaw becomes a competitive advantage. Whether you’re building a Moltbook‑style knowledge base or a next‑gen chatbot, the SDK gives you the low‑latency edge performance you need.

Ready to spin up your own instance? Explore the hosting options on UBOS for a managed, auto‑scaling deployment of OpenClaw.