GO SDK / V0

在 Go 服务中使用类型化 GoClaw 客户端。

Go SDK 由 OpenAPI 类型与一层面向 Run 的客户端组成，负责认证 Header、Workspace 作用域、幂等键和 Problem Details 映射。

01 / INSTALL

添加 SDK 依赖

当前 SDK 与主模块一起发布。开发阶段可以使用 latest；生产服务应固定经过验证的版本，避免无审查升级。

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

02 / CLIENT

创建 Workspace 客户端

Endpoint 指向 /api/v1，Token 使用短期 GoClaw Access Token，Workspace 使用稳定 ID。为 HTTPClient 设置与你的任务匹配的超时。

初始化

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
}

03 / RUN

创建并查询 Run

CreateRun 自动生成安全幂等键；需要跨进程重试时传入你持久化的业务键。返回的 replayed 表示服务端复用了先前结果。

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)

04 / ERRORS

使用类型化 ProblemError

API 非成功响应映射为 *goclaw.ProblemError。使用 errors.As 读取 Status、Code、RequestID、Retryable 和 Params，不要匹配错误字符串。

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

05 / METHODS

当前高层客户端能力

手写高层客户端目前覆盖 Run 创建、查询与取消，Approval 查询与决策，当前 Workspace 和用量摘要。其他 OpenAPI 操作可通过生成的 api 包访问。

写操作始终保留幂等键和请求关联信息。
不要把 Provider SDK 类型暴露到 GoClaw 集成边界。
升级 SDK 时同时审查 OpenAPI schema 与枚举变化。

06 / SECRETS

由部署环境注入 Token

应用启动时从 Secret Manager 读取 GOCLAW_TOKEN，不写入源码、镜像层、测试 Fixture 或结构化日志。Provider Key 只通过 Provider Credential API 管理。