文档中心

ArkClaw 企业版

请输入

命令详解

脚本和自动化

JSON 标准信封格式

CLI 携带 --json 参数时，输出固定标准化 JSON 信封，区分成功、失败两种结构。

执行成功结构

顶层 ok: true，业务数据存放于 data 对象：

{​
  "ok": true,​
  "data": {}​
}​

执行失败结构

顶层 ok: false，错误详情存放于 error 对象：

{​
  "ok": false,​
  "error": {​
    "code": "ARKCLAW_E_...",​
    "message": "...",​
    "hint": "..."​
  }​
}​

JSON 解析使用示例

# 仅提取 data 完整业务数据​
arkclaw agents --json | jq '.data' ​
​
# 纯文本提取对话返回内容​
arkclaw chat --clawid <ClawID> \​
  -m "返回一句话摘要" \​
  --json | jq -r '.data.reply'​

标准输出分离规范：

JSON 结构化数据仅输出至 stdout，用于程序解析。

进度打印、日志、提示文字输出至 stderr。

自动化脚本禁止合并 stdout、stderr 流后送入 JSON 解析器，会导致解析失败；如需屏蔽终端进度信息，单独过滤 / 丢弃 stderr。

退出码

退出码	分类	常见场景
0	成功	命令执行流程走完；包含「存在部分异常但整体流程结束」场景
1	API/业务错误	上游服务拒绝或返回错误；doctor 自检存在不通过项
2	参数或验证错误	参数缺失、资源不存在；删除操作无 --yes 确认（cron rm 除外）。cron rm 不适用：取消或输入结束时退出 0
3	认证错误	未登录、登录过期、STS 失败、无权访问资源
4	网络错误	服务端或端点不可达、连接中断；部分服务端响应格式、状态异常或任务失败当前也归入此类，例如 Agent Pack 上传响应或安装状态异常
5	CLI 内部错误	未归类异常

退出码 0 不代表业务全成功：

fanout 批量分发：部分实例调用失败，失败信息嵌入返回数组。

会话查询：云端不可达，降级读取本地缓存 sessions.json。

chat 对话超时：返回部分内容，data.timed_out = true。

定时任务删除：取消确认操作，无报错直接返回 0。

自动化脚本应同时检查退出码、JSON 顶层 ok 和具体业务字段。

doctor --json 是一个需要特别处理的组合：ok=true 只表示自检命令成功执行，data.healthy代表真实健康结果，存在失败项时该字段为 false。若检测出故障项，命令最终退出码为 1。

无人值守行为

对话交互限制：

批量脚本必须使用 -m 传入指令文本，禁止使用交互式 REPL 会话。

工具审批逻辑（自动放行规则）

优先加载本地 cmdpolicy.json 策略：

命中 deny 黑名单：直接拒绝，任何参数无法绕过。

命中 allow 白名单 / default: allow：自动放行工具调用。

策略为 default: ask、无匹配放行规则：无人值守环境无交互弹窗，默认拒绝所有工具。

支持 --approve-all 的普通命令可手动开启自动审批，但deny 黑名单仍最高优先级拦截。

删除类操作强制参数

删除 Agent、Netdisk 文件、定时任务，自动化脚本必须添加 --yes 自动确认。

登录认证限制

--no-browser 仅隐藏浏览器弹窗，不代表无人值守登录，首次登录仍需人工授权。

终端功能禁用

terminal 仅支持人工交互式终端，不可用于非交互脚本。

敏感操作

当前 CLI 暂未提供设备码（device-code）、环境变量 Token 这类全自动首次登录能力。若需实现完全无人值守的初始化认证，必须通过平台、管理员提供的官方合规身份方案完成鉴权；严禁将个人刷新凭证（refresh token）、管理员 AK/SK 硬编码写入自动化脚本、流水线配置。

最近更新时间：2026.07.23 11:42:18

这个页面对您有帮助吗？

有用

无用