安装 CLI 与创建环境
openagent-dev 0.11.7 是开发者的受控命令入口:它校验安装来源,处理 OAuth、安全凭据库、Workspace 来源选择、公钥绑定与真实 SSH 探测,还能查询已确认的业务 WebUI 端口和调用公开 Developer Portal 操作。不要用旧版 0.2.x 的命令表判断当前能力。
安全安装:只从可信提示词进入
复制完整 Build With Local Agent 提示词
提示词把当前agent_id、agent_version_id与固定 Skill 入口绑定在一起。原样交给本地 AI,不替换 URL、摘要或 ID。执行 Skill 中的受限 bootstrap
bootstrap 校验 HTTPS、大小、响应头摘要和正文 SHA-256,再调用脚本自身安装。下面只解释最终安装参数,真正下载步骤必须使用本次 Skill 给出的值:# Windows(已校验的临时文件) py <已校验的-openagent-dev.py> install --expected-sha256 <Skill绑定的SHA-256> # macOS / Linux python3 <已校验的-openagent-dev.py> install --expected-sha256 <Skill绑定的SHA-256>用返回的绝对命令核对版本
安装 JSON 返回command、installed_path和path_hint。先运行返回的完整command --version,必须是0.11.7或更新;PATH 中另一个旧副本不能作为证据。
摘要不一致必须停止
CLI_DIGEST_MISMATCH 表示文件与 Skill 绑定版本不同。删除本次临时下载,从官网重新生成可信提示词;不要忽略校验或修改 expected digest。
先做只读检查
openagent-dev --version
openagent-dev auth status
openagent-dev doctor
openagent-dev workspace sources --version-id <agent_version_id>
doctor 检查 Python、OpenSSH、ssh-keygen、本地回环和已有公钥,不修改远端。workspace sources 返回当前可续用 Workspace、可恢复的历史版本和 fresh 选项;先把实际选项展示给开发者确认,不能把 recommended_source_version_id 当自动授权。
创建或续用正确的 Workspace
续用已有 Sandbox
sources 返回 existing_workspace 时,保留现场并用该 ID 查询/连接,不再 create。
恢复已发布快照
开发者确认来源后,用 --source-version-id 创建独立 Workspace。
从基础环境开始
开发者明确选择空白环境时使用 --fresh。
# 从已确认的来源版本恢复
openagent-dev workspace create --version-id <目标draft版本ID> --source-version-id <来源版本ID>
# 明确使用平台基础环境
openagent-dev workspace create --version-id <目标draft版本ID> --fresh
创建命令会轮询到 active、终态或超时,但不会读取、生成或上传本机公钥。来源快照只提供代码、文件和依赖,不复制来源版本的 Card、Pricing、模型、Resources 或 WebUI 端口。
超时后继续查询原 Workspace
openagent-dev workspace status --workspace-id <WORKSPACE_TIMEOUT返回的ID>
超时只是本次等待耗尽,不等于创建失败。不得用新的 create 隐藏未知结果,也不要并发启动多个 status。
active 后必须 connect
openagent-dev workspace connect --workspace-id <workspace_id>
新 Workspace 可以是 status=active 但 ssh_binding_status=unbound。connect 会:
- 从本机私钥导出公钥,确认公私钥匹配。
- 对 unbound Workspace 使用稳定幂等意图绑定公钥;binding 状态只允许用同一 key 恢复。
- 使用 Workspace 独立 known_hosts 做 host key 保护。
- 以
-vvv、IdentitiesOnly=yes和BatchMode=yes执行真实认证探测。
连接完成门
只有 CLI 返回 ssh_binding_status=bound 且 ssh_verified=true,才使用该结果里的完整 ssh_command 和 scp_command。不要直接执行旧 status 响应或手工拼 host、端口、用户、key 参数。
本机没有 key 时,创建动作会修改用户文件,必须先明确同意:
openagent-dev ssh-key ensure --create
# 或在明确的新路径创建
openagent-dev ssh-key ensure --create --path <新私钥路径>
连接过期与 resume
openagent-dev workspace resume --workspace-id <workspace_id>
resume 只在开发者明确继续使用同一 active + expired Workspace 时续签短期连接和稳定 Gateway 会话;不新建 Sandbox、不绑定/覆盖 key。需要 SSH 仍要再用 connect 验证。
Workspace 成功摘要
{
"workspace_id": "dws_example",
"agent_id": "agt_example",
"version_id": "sav_example",
"source_version_id": "sav_source_or_null",
"status": "active",
"connection_status": "ready",
"ssh_binding_status": "bound",
"ssh_verified": true,
"remote_project_dir": "/oasn",
"webchat_url": "https://...",
"webui_urls": [],
"ssh_command": "ssh -vvv ...",
"scp_command": "scp ...",
"expires_at": "..."
}
字段以当前 CLI 实际 JSON 为准;上面是脱敏完成门示例,不要复制其中 ID/URL。Sandbox 内还会注入非敏感的 OASN_AGENT_ID 和 OASN_AGENT_VERSION_ID;它们是身份上下文,不是 Token 或 Owner 授权。
WebUI 查询与 Portal 命令
# CLI 0.11.0:查询已确认端口及当前连接
openagent-dev version webui-ports get --version-id <agent_version_id>
# 列出当前部署的官网开发者操作
openagent-dev portal commands
业务端口来自已确认配置及平台配置,CLI 不再替换、清空或刷新端口,不支持任意端口编辑。查询返回 sandbox_id、failure_code 和连接状态;缺失或过期连接由平台按原配置的读回流程恢复。pending 可稍后查询,failed 必须报告原错误,不能伪称 ready 或无限等待。
仅在 sync_status=ready 与 proxy_status=ready 同时成立时交付 webui_urls。CLI 会校验开发入口 /sandbox-proxy/{sandbox_id}/{port}/,使用完整返回 URL 并实际测试 HTTP 页面和 WebSocket。完整步骤见 结构化输入与 WebUI JSON。Portal 写操作仍须对应开发者已明确要求的当前动作,并携带命令要求的确认、ETag 和幂等参数。
命令边界速查
| 类别 | 当前主要命令 | 关键边界 |
|---|---|---|
| 认证 | auth status/login/logout | 凭据只进系统安全存储。 |
| Workspace | sources/create/status/connect/resume | 来源需确认;active 不代替 connect;resume 不代替 SSH 验证。 |
| WebUI | version webui-ports get | 查询已确认端口;缺失或过期连接由平台读回流程恢复,failed 保留原错误。 |
| 官网 | portal commands 及其列出的操作 | 写入必须按单一当前意图确认和幂等。 |
| 兼容 | skill-link create | 主路径仍优先官网可信提示词。 |
CLI 没有通用 sync,也没有 workspace close/delete/publish。代码同步按 安全同步 使用 connect 返回的参数;发布/上线按当前网站或 portal commands 明确列出的受控操作执行,不能猜原始 API。
常见连接错误不要合并处理
| 错误 | 下一步 |
|---|---|
SSH_AGENT_KEY_NOT_LOADED / SSH_PRIVATE_KEY_PASSPHRASE_REQUIRED | 在同一用户会话解锁或加载 CLI 已选择的原私钥,对同一 Workspace 重跑 connect;不换 key。 |
SSH_CONNECTION_FAILED | 按 reason 区分 timeout、refused、dns、unreachable、closed;对比本机网络和平台入口。 |
SSH_AUTHENTICATION_FAILED | 连接已到 sshd 后才检查绑定指纹传播和服务端认证日志;不覆盖 authorized_keys。 |
SSH_HOST_KEY_CHANGED | 立即停止,不重试、不覆盖隔离 known_hosts。 |
完整参数表和 WebUI 状态处理见 CLI 命令参考。