开始使用
OpenAgent 开发者文档
这份手册面向第一次接手 OpenAgent 的开发者，覆盖从官网创建草稿、在隔离 Workspace 中编写 Program、通过 WebChat 验证，到发布并上线的完整闭环。按“快速开始”顺序操作，不需要预先了解平台内部服务。
推荐主路径
在官网版本工作台点击 Build With Local Agent，复制完整可信提示词并原样交给本地 AI。提示词已经绑定当前 Agent 和版本，本地 AI 会按平台 Skill 使用受校验的 CLI 建立开发 Workspace。
完成后你将得到什么
- 一个属于当前账号的 OpenAgent，以及一个可继续编辑的 draft 版本。
- 一个状态为
active的隔离开发 Workspace，项目目录固定为/oasn。 - 能在 Workspace WebChat 中运行的 Agent Program，并完成正常、边界和失败场景验证。
- 完整的 Agent Card、MOM、模型能力、CPU/Memory 与定价配置。
- 一个已发布、由开发者明确执行 Go Online，并从公开 Agent 页安装到 ChatGPT、Claude 或 WorkBuddy 后完成正式调用验收的版本。
开发闭环
创建 Agent 与首个草稿
登录官网进入 Developer，点击 Create。当前实现会同时创建 Agent 和它的第一个 draft 版本，并进入版本工作台。把版本上下文交给本地 AI
在版本工作台点击 Build With Local Agent，复制完整可信提示词。不要改 Skill URL、操作类型或其中绑定的 ID。创建 Workspace 并实现 Program
本地 AI 通过 CLI 完成浏览器登录、来源选择、Workspace 创建、公钥绑定和真实 SSH 探测。只有status=active且 connect 返回ssh_binding_status=bound、ssh_verified=true后，才使用返回的 SSH/SCP 信息。补齐展示与计费配置
回到版本工作台配置 Agent Card、MOM、模型能力、Resources 中的 CPU/Memory 和 cost-plus 定价，然后保存草稿。验证、发布、上线
先在 WebChat 完成开发测试，再发布。发布成功后的默认状态是 Offline；点击 Go Online 后，从发布结果的公开 Agent 链接（或公开 Agents 列表的准确名称搜索结果）打开详情，通过 Use in ChatGPT/Claude/WorkBuddy 安装，并从实际客户端完成一次正式调用。
三个 ID，不要混用
| 标识 | 代表什么 | 何时需要 | 可靠来源 |
|---|---|---|---|
agent_id | Agent 的长期身份 | 查看 Agent 详情、可信提示词绑定上下文 | 官网 Agent 详情；Build With Local Agent 生成的完整提示词 |
agent_version_id | 某个具体 draft/版本 | 创建开发 Workspace、绑定本次构建 | 版本工作台 URL；可信提示词 |
workspace_id | 一次隔离开发环境 | 创建超时后续查状态、定位当前 Workspace | CLI 创建结果或 WORKSPACE_TIMEOUT 错误 |
不要凭名称、URL 片段或历史记录猜 ID
主路径中的可信提示词已经携带 Agent 与版本上下文，本地 AI 不应再次要求你手工输入这两个 ID。创建 Workspace 超时后，使用错误中返回的 workspace_id 查询原 Workspace，不要重复创建。
官网、CLI 与 Workspace 的职责
| 界面 | 负责 | 不负责 |
|---|---|---|
| 官网版本工作台 | 创建/编辑版本、模型、CPU/Memory、Agent Card、定价、发布、上线/下线 | 不直接编辑远程文件 |
| CLI 0.7.3 | 受校验安装、诊断/登录、来源选择、Workspace 创建/连接/续签、WebUI 端口和公开 Portal 操作 | 没有通用 sync 或 workspace close/delete/publish；写操作仍需明确授权 |
| 开发 Workspace | 在 /oasn 实现 Program，并通过 WebChat 做开发测试 | 不替代官网的版本发布和上线动作 |
开始前准备
- 可访问 OpenAgent 官网的浏览器和开发者账号。
- 能执行 Python 3、OpenSSH
ssh与ssh-keygen的本机环境。Windows 安装脚本和生成的oasn-sa-dev.cmd默认使用 Python Launcherpy；先确认py --version可运行。只有python.exe而没有py时，不要继续使用该 shim，应通过python <CLI 安装路径> ...显式运行，并在安装记录中保存该路径。 - 能读取平台 Skill URL、运行终端命令并展示差异的本地 AI。
- 为新建 SSH 密钥、连接 Workspace、同步文件分别做明确授权的操作者。