Direct answer: Integrate Gog with OpenClaw by treating Gog as any external service: register an API client with Gog (or obtain API keys) and implement the explicit auth flows (OAuth2 or API keys) that Gog requires; create an OpenClaw skill and install/configure it through ClawHub with those credentials stored securely; implement the runtime logic that the OpenClaw agent will call (or that the skill’s webhooks will call) as standard HTTPS endpoints; keep stateful systems (token storage, refresh, rate-limit queues, background syncs) outside the agent runtime; validate webhooks and API responses, and debug by checking logs, API responses, credential scopes, and invocation traces. The steps below explain how to do that in practical, working terms and include generic, real HTTP/Node.js examples you can adapt to Gog’s actual endpoints and docs.

Overview: what “integrating Gog with OpenClaw” actually means

• Treat Gog as an external API provider. Discover whether Gog exposes OAuth2 or API keys, webhooks, or only a private API. Use their official developer docs; if none exist, you must obtain an account and confirm supported mechanisms.
• Configure the OpenClaw skill via ClawHub. Install the skill through ClawHub and supply the credentials (client id/secret or API key) in the configuration that ClawHub provides for the skill (store secrets securely; do not hard-code in the skill bundle).
• Separate runtime concerns. Keep short-lived, stateless execution in the agent; store tokens, rate-limit state, and long-running sync jobs outside the agent (database, worker queue, cron/scheduler).
• Validate and monitor. Validate webhook signatures, check API responses, rotate credentials, and use logs and metrics for debugging.

Prerequisites and discovery

• Find Gog’s developer documentation or contact their platform team to learn supported authentication (OAuth2, API key), rate limits, resource endpoints, and webhook support.
• If Gog has no public API, request partner access or use a documented partner API. Avoid scraping user interfaces—prefer official APIs or partner agreements.
• Decide what you need from Gog: user purchases, wishlist, game metadata, license activation—this determines scopes you’ll request or keys you’ll need.

Authentication patterns (vendor-neutral, real code examples)

• OAuth2 (recommended for per-user Gog access): Perform the standard authorization code flow: redirect user to Gog’s authorize URL, receive code at your redirect URI, exchange the code for an access token + refresh token. Store refresh tokens in a secure database and refresh access tokens before they expire.
• API key / service account: If Gog provides an API key for a service account, store it as a secret (environment variable or secret store) and use it in Authorization headers on requests. Respect the key’s scopes and IP restrictions if any.
• Webhook signing: If Gog sends webhooks, get the webhook secret and validate payload signatures (HMAC/SHA256 style) to prevent spoofing.

Skill configuration through ClawHub (vendor-neutral guidance)

• Create/prepare the skill bundle that knows how to call Gog’s APIs. The skill's code should expect credentials to be injected via environment variables or a secure config store managed by ClawHub.
• In ClawHub, install the skill and configure the values required: client_id, client_secret, redirect URLs, webhook secret, API key, and any environment flags. Avoid embedding secrets into code; use ClawHub’s secure secret or env mechanism.
• Define the permission scopes the skill needs and make that explicit in the skill config so operators can review and approve them before install.

Runtime architecture: what runs in the agent vs what runs externally

• Agent (OpenClaw skill runtime): Short-lived request/response handlers that execute user-invoked tasks (e.g., "show my Gog purchases", "add to wishlist"). Agents should call Gog’s API directly using the stored credentials and return results.
• External services: Token storage and refresh logic, background polling/synchronization with Gog, rate-limit queues, job retries, and persistent logs should live outside the agent (database + worker or server). For reliability, run these on standard infrastructure (cloud VMs, serverless functions, containers, or managed services).
• Webhooks: Configure a webhook receiver endpoint hosted outside the agent (or in the skill runtime if the platform supports stable endpoints). Validate signatures and push events into your internal queue for processing by workers.

Example: OAuth2 flow (Node.js + express, generic endpoints)

// Example uses node-fetch (npm install node-fetch@2 express)
const express = require('express');
const fetch = require('node-fetch');
const app = express();

// <b>//</b> Replace with Gog's actual endpoints and client credentials
const CLIENT_ID = process.env.GOG_CLIENT_ID;
const CLIENT_SECRET = process.env.GOG_CLIENT_SECRET;
const AUTH_URL = 'https://gog.example.com/oauth/authorize';
const TOKEN_URL = 'https://gog.example.com/oauth/token';
const REDIRECT_URI = 'https://your-app.example.com/oauth/callback';

// <b>//</b> Step 1: Redirect user to Gog's authorize URL
app.get('/auth/start', (req, res) => {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'purchases wishlist', // <b>//</b> adjust to Gog's scopes
    state: 'secure-random-value' // <b>//</b> CSRF protection
  });
  res.redirect(`${AUTH_URL}?${params.toString()}`);
});

// <b>//</b> Step 2: Callback to exchange code for tokens
app.get('/oauth/callback', async (req, res) => {
  const code = req.query.code;
  const body = new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    redirect_uri: REDIRECT_URI,
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET
  });
  const tokenResp = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: body.toString()
  });
  const tokenJson = await tokenResp.json();
  // <b>//</b> Persist tokenJson.access_token, tokenJson.refresh_token, and tokenJson.expires_in in your DB
  res.json(tokenJson);
});

app.listen(3000);

Example: calling Gog’s API from a skill (Node.js)

// <b>//</b> Simple request to fetch user purchases using a stored access token
const fetch = require('node-fetch');

async function fetchGogPurchases(accessToken) {
  // <b>//</b> Replace with Gog's purchases endpoint
  const url = 'https://api.gog.example.com/v1/user/purchases';
  const resp = await fetch(url, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Accept': 'application/json'
    }
  });
  if (!resp.ok) {
    const err = await resp.text();
    throw new Error(`Gog API error ${resp.status}: ${err}`);
  }
  return resp.json();
}

Example: verifying webhooks (generic HMAC/SHA256)

// <b>//</b> Use crypto to validate signature header (e.g., X-Gog-Signature)
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signatureHeader, webhookSecret) {
  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(rawBody);
  const expected = `sha256=${hmac.digest('hex')}`;
  // <b>//</b> Compare in constant time
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Secrets, token lifecycle, and rotation

• Store client_id and client_secret in a secrets manager or as encrypted environment variables configured in ClawHub. Do not expose secrets in logs or in the skill bundle.
• Persist refresh tokens and associate them with a user record in a secure database (encrypted at rest). Use refresh tokens to obtain new access tokens when the access token expires.
• Implement token refresh with backoff and retry on transient errors. Revoke/rotate credentials when compromise is suspected or when a user deauthorizes the app.

Error handling, monitoring, and debugging checklist

• Check the agent and external service logs (request/response bodies, status codes). Capture correlation IDs if your system and Gog support them.
• Inspect HTTP responses: status code, response body, and any error codes in Gog’s API payload.
• Verify OAuth scopes match what you requested and what Gog granted. A missing scope often causes 403/insufficient scope errors.
• Confirm that the skill is installed and configured in ClawHub and that the credentials installed there are the ones used at runtime.
• Validate webhook signature failures by comparing the raw payload used for HMAC computation. Webhook middleware sometimes buffers/encodes bodies — use raw body bytes for signature checks.
• Check rate-limit headers and implement throttling (retry-after handling and exponential backoff).

Security and permission boundaries

• Request the minimum scopes required. Make usage and required scopes explicit in the skill’s configuration so admins can make informed decisions during install.
• Do not store user passwords. Use OAuth or service accounts only.
• Protect webhooks and callback endpoints with TLS and validate signatures.
• Use least-privilege for any service account keys and restrict origin IPs if supported.

Deploy, scale, and reliability tips

• Run webhook receivers and token refresh workers in infrastructure with high uptime (not ephemeral agent containers if those are short-lived in your environment).
• Queue webhook events and process them asynchronously to absorb spikes and retries. Use exponential backoff for transient API errors.
• Monitor errors, latency, and success rates. Add alerting for repeated auth failures, rate-limited endpoints, or webhook verification failures.

What to avoid and common pitfalls

• Don’t assume Gog supports a particular endpoint or authentication method — confirm via Gog’s docs or partnership channels.
• Don’t embed secrets in the skill bundle or logs. Don’t run long-lived background jobs inside ephemeral agent runtime unless it’s guaranteed persistent.
• Don’t skip webhook signature validation or scope checks; these are common attack vectors or sources of misconfiguration.