CLI / GOCLAW

从终端提交、检查和治理 Run。

goclaw 是面向 Workspace 用户的终端客户端。它调用生产 HTTP API，支持稳定退出码和 table、JSON、YAML 输出。

01 / INSTALL

安装 goclaw

当前公开安装入口需要 Go 1.26 或更高版本。命令会把 goclaw 安装到 GOBIN；未设置 GOBIN 时使用 GOPATH/bin。

安装并检查版本

go install github.com/menglingwei/goclawai/cmd/goclaw@latest
goclaw version

首个签名二进制 Release 发布前，生产自动化应把 @latest 替换为经过验证的明确版本或提交。

02 / CONNECT

连接 Workspace

CLI 使用生产 API、Workspace ID 和短期 Access Token。通过 Secret Manager 注入 Token；不要使用 Provider Key，也不要把 Token 写入命令参数或仓库文件。

设置当前终端会话

export GOCLAW_ENDPOINT=https://goclawai.com/api/v1
export GOCLAW_WORKSPACE=ws_your_workspace
export GOCLAW_TOKEN=your_short_lived_access_token

goclaw doctor
goclaw workspace current

当前 CLI 不提供交互式登录。GOCLAW_TOKEN 需要来自已注册 OAuth 客户端或你的 Workspace 管理员。

03 / SUBMIT

从 JSON 提交 Run

请求文件必须包含 workload、provider 和 region，未知字段会被拒绝。为同一个业务操作固定幂等键，超时后可安全重试。

run.json

{
  "workload": {"image": "alpine"},
  "provider": "auto",
  "region": "auto"
}

goclaw run submit --file run.json \
  --idempotency-key onboarding-run-001 \
  --output json

04 / OPERATE

查询、取消和查看用量

run get 返回状态、Provider 与派生 Condition。cancel 只请求取消；继续查询直到 cancellationStatus 与 cleanupStatus 到达终态。

goclaw run get run_123
goclaw run cancel run_123 --idempotency-key cancel-run-123
goclaw usage summary --output json

05 / APPROVAL

显式处理高风险审批

先读取 Approval 的风险等级、限制、过期时间和 version，再用 expected-version 决策。版本不匹配会冲突，避免覆盖其他审批人的决定。

goclaw approval get appr_123 --output json

goclaw approval approve appr_123 \
  --expected-version 1 \
  --reason reviewed_change

# Or reject it
goclaw approval deny appr_123 --expected-version 1 --reason unsafe_scope

06 / AUTOMATE

为脚本使用稳定输出和退出码

自动化使用 --output json。stdout 只承载结果；非零退出码区分用法、认证、授权、未找到、冲突、超时和 Provider 不可用。

使用 goclaw completion zsh|bash|fish|powershell 生成补全。
使用 goclaw mcp metadata 检查 MCP 发现文档。
调试信息也不应包含 Token、Provider Key 或 Run 正文。

0 success       1 generic failure
2 usage         3 authentication
4 authorization 5 not found
6 conflict      7 timeout
8 provider unavailable