openagent-dev 命令参考

命令清单以 CLI 0.11.0 为基线。请通过当前开发者 Skill 安装 openagent-dev。

本页按当前解析器命令树整理。命令输出为 JSON;所有下载 URL 和 SHA-256 都以当前官网 Build With Local Agent 返回的可信 Skill 为准,不能从离线手册固化。

安装与本机检查

命令用途是否修改状态
openagent-dev --version显示实际执行的 CLI 版本;从 0.11.7 起使用更名后的命令。否
openagent-dev doctor检查 Python、SSH、ssh-keygen、本地回环端口与已知公钥。否
install --expected-sha256 SHA把已经按 Skill 校验的脚本安装到当前用户目录。只写本机安装目录
# Windows(对已校验的临时脚本)
py openagent-dev.py install --expected-sha256 <Skill绑定的64位SHA-256>

# macOS / Linux
python3 openagent-dev.py install --expected-sha256 <Skill绑定的64位SHA-256>

安装结果返回 installed_path、command 和 path_hint。先用返回的完整 command 再执行 --version;若 PATH 仍指向旧副本,不要反复安装或自行修改 shell 配置。

认证与 SSH key

openagent-dev auth status
openagent-dev auth login
openagent-dev auth logout

openagent-dev ssh-key ensure
openagent-dev ssh-key ensure --create
openagent-dev ssh-key ensure --create --path <新私钥路径>
  • auth status 只查安全凭据库;auth login 用于明确重试 OAuth;需要认证的其他命令也会按需启动浏览器。
  • auth logout 分别报告本地删除和服务端吊销结果;server_status=unconfirmed 不能当作已确认撤销。
  • 未加 --create 的 ssh-key ensure 只查找/校验公钥。创建新 key 必须取得明确授权,目标已存在时 CLI 拒绝覆盖。
  • 私钥始终留在本机;平台只接收公钥。CLI 使用系统 Credential Manager、Keychain 或 Secret Service,不回退到明文会话文件。

选择来源、创建并连接 Workspace

1. 只读查询来源

openagent-dev workspace sources --version-id <agent_version_id>

结果可能提供当前 existing_workspace、可恢复的已发布版本与 recommended_source_version_id。推荐项不是自动授权;开发者必须在“续用已有 Workspace / 指定历史快照 / fresh 基础环境”中明确选择。

2. 创建或续用

# 基于开发者确认的已发布版本快照
openagent-dev workspace create --version-id <目标draft版本ID> --source-version-id <来源版本ID>

# 明确从平台基础环境开始
openagent-dev workspace create --version-id <目标draft版本ID> --fresh

# 只读查询已知 Workspace 生命周期
openagent-dev workspace status --workspace-id <workspace_id>

来源 Version 只恢复兼容的代码/文件快照,不复制 Agent Card、Pricing、模型、资源规格或 WebUI 端口。若 sources 已返回可续用的 Workspace,就使用其 ID,不用 create 覆盖。

3. 绑定公钥并真实验证 SSH

openagent-dev workspace connect --workspace-id <workspace_id>

status=active 只表示生命周期就绪,不证明 SSH 可用。workspace connect 会核对本机公私钥、按稳定幂等意图绑定未绑定 Workspace、使用 Workspace 隔离的 known_hosts,并执行真实 -vvv 认证探测。只有返回 ssh_binding_status=bound 且 ssh_verified=true 后,才逐字执行结果中的完整 ssh_command/scp_command。

4. 仅续签短期连接

openagent-dev workspace resume --workspace-id <workspace_id>

只在开发者明确要求继续使用同一 active + expired Workspace 时执行。resume 不新建 Sandbox、不绑定 SSH key,也不替代后续 workspace connect 的认证探测。

等待参数

参数范围默认值
--timeout-seconds30..3600600
--poll-interval-seconds1..303
--login-timeout-seconds60..600300

WebUI 业务端口

CLI 0.11.0 或更新版本仅支持以下查询:

# 查询已确认端口及当前连接
openagent-dev version webui-ports get --version-id <agent_version_id>
  • 端口来自已确认配置和平台配置。CLI 不再替换、清空或刷新端口,也不支持任意端口编辑。
  • 返回 sandbox_id、failure_code、ports、revision、sync_status、proxy_status 和 webui_urls;端口 revision 不是官网草稿 ETag。
  • 缺失或过期连接由平台按同一已确认配置的读回流程恢复,不为续期重跑配置或重建沙箱。
  • pending 可稍后查询;sync_status=failed 必须报告 failure_code。旧写意图退役是失败,不能当作无限等待的 pending 或 ready。
  • 两项状态均 ready 才交付 URL。CLI 会校验 /sandbox-proxy/{sandbox_id}/{port}/;使用完整返回值,并继续真实验证 HTTP 页面及 WebSocket 行为。

官网开发者操作

# 离线列出当前部署支持的官网操作及写入属性
openagent-dev portal commands

0.11.0 的 portal 命令使用与官网相同的公开接口。只读命令可直接查询;写命令必须是开发者已经明确要求的当前动作,并携带命令要求的 --confirm、稳定 --idempotency-key、原始带引号 --if-match 或临时 --body-file。具体操作和参数以本机 portal commands 与 --help 为准,不从旧手册猜测。

openagent-dev skill-link create --version-id <VERSION_ID>

这是仍被解析器接受的兼容入口。推荐主流程仍是在官网点击 Build With Local Agent,复制绑定当前 Agent/Version 的完整可信提示词。

仍然不存在或不能替代的操作

写法/想法当前事实正确路径
openagent-dev sync没有通用同步命令。经授权后按 安全同步 使用 connect 返回的精确 SSH/SCP 参数。
openagent-dev workspace close/delete/publish没有这些 Workspace 子命令。不要拼内部 API;发布使用网站或已列出的受控 portal 操作。
直接执行 status 中旧 SSH 字符串不能证明 key 绑定、host key 或认证通过。先运行 workspace connect。
直接调用原始平台 HTTP绕过 CLI 的认证、幂等、摘要与脱敏边界。使用公开 CLI 命令或官网。

常见稳定错误

错误处理
CLI_DIGEST_MISMATCH停止;从当前 Skill 重新取得绑定下载信息,不能改 expected digest。
WORKSPACE_TIMEOUT保留返回的 Workspace ID,用 status 继续查询,不重复 create。
SSH_AGENT_KEY_NOT_LOADED / SSH_PRIVATE_KEY_PASSPHRASE_REQUIRED在同一用户会话解锁/加载原私钥,然后对同一 Workspace 重跑 connect;不换 key。
SSH_HOST_KEY_CHANGED立即停止,不做网络重试或覆盖 known_hosts。
SSH_CONNECTION_FAILED按返回的 timeout/refused/dns/unreachable/closed 原因区分网络与平台入口。
DEVELOPER_WORKSPACE_WEBUI_WRITE_RETIRED保留 failure_code;旧写意图已失败,不能伪称 ready 或无限等待。
PORTAL_RESULT_UNKNOWN写操作结果未知;按同一业务意图查询/恢复,不换 idempotency key 重提。