Use a typed GoClaw client in your Go service.

Add the SDK dependency

The SDK currently ships with the main module. latest is acceptable for evaluation; production services should pin a reviewed version.

go get github.com/menglingwei/goclawai/sdk/go@latest

Create a workspace client

Point Endpoint at /api/v1, use a short-lived GoClaw access token, and identify the workspace by stable ID. Set an HTTP timeout appropriate for your operation.

client, err := goclaw.New(goclaw.Config{
    Endpoint:  "https://goclawai.com/api/v1",
    Token:     os.Getenv("GOCLAW_TOKEN"),
    Workspace: os.Getenv("GOCLAW_WORKSPACE"),
    HTTPClient: &http.Client{Timeout: 30 * time.Second},
})
if err != nil {
    return err
}

Create and inspect a Run

CreateRun generates a safe idempotency key by default. For cross-process retries, pass a durable business key. replayed reports whether the server reused an earlier result.

run, replayed, err := client.CreateRun(ctx, api.CreateRunRequest{
    Provider: "auto",
    Region:   "auto",
    Workload: map[string]any{"image": "alpine"},
}, "onboarding-run-001")
if err != nil {
    return err
}

current, err := client.GetRun(ctx, run.Id)

Use typed ProblemError values

Non-success API responses map to *goclaw.ProblemError. Use errors.As to inspect Status, Code, RequestID, Retryable, and Params rather than matching strings.

var problem *goclaw.ProblemError
if errors.As(err, &problem) {
    log.Printf("code=%s request=%s retryable=%t",
        problem.Code, problem.RequestID, problem.Retryable)
}

Current high-level client surface

The high-level client currently covers Run create, get, and cancel; Approval get and decide; current workspace; and usage summary. The generated api package exposes the remaining OpenAPI operations.

• Preserve idempotency keys and request correlation on writes.
• Do not expose provider SDK types across the GoClaw integration boundary.
• Review OpenAPI schema and enum changes with every SDK upgrade.

Inject tokens from the deployment environment

Read GOCLAW_TOKEN from a secret manager at process start. Keep it out of source, image layers, test fixtures, and structured logs. Manage provider keys only through Provider Credentials.