从 Workspace 到第一条可追踪 Run。

登录并确认 Workspace

进入 Console 后先确认当前 Workspace。成员、Provider Credential、Skill、Run、额度和审计记录都严格归属于该 Workspace。

• 不要在不同 Workspace 之间复用访问令牌。
• 自动化请求应保存 Workspace ID，而不是名称。

绑定并验证模型凭据

在 Console 的 Model Provider 区域创建凭据并执行验证。GoClaw 只回显脱敏元数据；Provider Key 不会出现在读取接口、日志或 Artifact 中。

Provider Key 与 GoClaw Access Token 是两类凭据：前者调用模型，后者授权用户或客户端访问 Workspace。

选择适合你的入口

交互试用使用 Playground；脚本和服务使用 HTTP API 或 Go SDK；终端自动化使用 goclaw；外部 Agent 客户端使用 MCP。它们共享相同的权限、审批与审计语义。

提交后按状态推进

Run 创建成功返回 202。随后查询状态或订阅可恢复 SSE；遇到高风险操作时读取 Approval，在核对限制与版本后批准或拒绝。

• 写请求携带稳定 Idempotency-Key，安全重试。
• 取消是请求，不等于资源已经清理完成。
• 流断开后使用 Last-Event-ID 恢复，避免丢事件。

把 Artifact 当作交付物

Agent Run 完成后下载 Artifact。它记录模型、Token 用量、固定 Skill 版本、Tool 调用摘要和校验摘要，适合进入工单、评测或发布证据链。

不要把 Run 输入、模型输出或 Artifact 复制到公开 Issue；它们可能包含用户数据。

先验证，再扩大自动化

先用低风险请求验证 Workspace、模型和输出格式，再接入审批、重试、事件恢复和 Artifact 下载。生产客户端必须处理 401、403、409、429 与 5xx。