这套文档帮助你把一个业务想法做成可以使用的 OpenAgent。你不需要先了解平台内部架构；从你的任务、输入和预期结果开始即可。

一个 OpenAgent 需要准备什么

• 程序：决定 Agent 怎样理解用户要求、使用工具和生成结果。
• 介绍：告诉用户它适合做什么，需要提供什么。
• 价格：说明使用方式和收费设置。

推荐顺序

1. 登录并创建一个草稿版本。
2. 编写程序，放到云端开发环境中。
3. 用真实示例测试回复、文件和交互网页。
4. 完善介绍与价格，确认后发布。
5. 查看发布结果，并从用户入口再测试一次。

按你当前的问题阅读

• 第一次上手：创建你的第一个 OpenAgent
• 已有代码：编写 Agent 程序
• 需要上传文件：安全上传本地代码
• 需要展示网页：为结果添加交互网页
• 准备上线：准备发布
• 卡在某一步：常见问题与解决方法

什么才算完成

开发页面能打开，只说明你可以开始测试。上线前还要确认 Agent 能完成真实任务；发布后要再检查一次用户实际拿到的文本、文件或网页。

本离线包可以直接阅读。文中的官网链接只有在你主动点击时才需要联网。

本页带你完成一个可验证的结果：创建或续用开发环境，让默认 Agent 按你写的规则回答一次真实请求。这里不会发布 Agent，也不会产生正式用户流量。

开始前

准备好开发者账号、本地 Python 3.10 或以上版本，以及可以打开的浏览器。连接云端环境还需要 OpenSSH。

下载官方开发技能包，按包里的说明安装 oasn-sa-dev。技能包可指导本地 AI 助手操作，命令行工具负责实际执行。

安装后先确认当前命令确实是 0.6.0 或更新版本：

oasn-sa-dev --version
oasn-sa-dev doctor

如果安装结果给出了命令的绝对路径，优先使用该路径检查版本。不要因为系统中仍有同名旧工具而反复安装。

没有 Agent 或草稿版本时，先按创建 Agent 和草稿版本操作。

1. 登录并选定草稿

oasn-sa-dev portal session
oasn-sa-dev auth status
oasn-sa-dev portal agents --limit 20
oasn-sa-dev portal versions --agent-id <agent_id> --limit 20
oasn-sa-dev portal version --version-id <agent_version_id>

使用当前查询结果中的编号。确认版本可以编辑，且属于你准备开发的 Agent。不要通过名字猜测编号。

2. 确认环境从哪里开始

oasn-sa-dev workspace sources --version-id <agent_version_id>

根据返回结果选择一种情况：

• 已有开发环境：查询并继续使用返回的 workspace_id，不要再创建。
• 推荐了可恢复的已发布版本：确认确实要从该版本继续后，记录它的 source_version_id。
• 第一次开发，没有历史版本：明确选择从基础环境开始。

目标草稿版本和来源版本是两个不同编号。来源决定初始文件，后续修改仍保存到目标草稿。

3. 创建或继续云端开发环境

从已确认的历史版本继续：

oasn-sa-dev workspace create --version-id <agent_version_id> --source-version-id <source_version_id>

第一次开发并明确选择基础环境：

oasn-sa-dev workspace create --version-id <agent_version_id> --fresh

如果上一步返回了已有环境，只查询它：

oasn-sa-dev workspace status --workspace-id <workspace_id>

如果工具提示缺少 SSH 公钥，确认愿意创建一对专用密钥后，再执行：

oasn-sa-dev ssh-key ensure --create

等待返回 status=active 和 connection_status=ready。前者表示环境已创建，后者表示当前连接可用。使用返回的完整连接命令和对话页面链接。

4. 写入第一个业务规则

使用工具本次返回的完整 SSH 命令进入云端。业务文件放在 /oasn，所有请求从名为 main 的默认 Agent 开始。

在 /oasn/AGENTS.md 写入下面的完整内容：

# 三点摘要助手

当用户提供需要总结的文字时：

1. 只根据本次提供的文字回答。
2. 返回恰好三条简短结论。
3. 内容不足时说明还缺少什么，不自行补写事实。

保存后确认文件位于 /oasn/AGENTS.md。已有本地项目时，不要用整个项目覆盖这个示例；改按安全上传步骤传入经过检查的副本。

5. 做一次可判断结果的测试

打开本次返回的对话页面，发送：

请总结以下内容：本周完成登录改造、文件下载修复和发布演练；下周准备补充性能测试。

预期结果是恰好三条结论，而且只使用这段文字中的信息。回复不符合时，先检查 /oasn/AGENTS.md 是否保存正确，以及 main 是否能读取它。

再发送：

请总结。

预期结果是请你补充要总结的内容，而不是编造一份摘要。

6. 记录结果并选择下一步

到这里，完成的是开发环境中的最小文本测试。记录使用的目标版本、环境编号、两个测试请求和实际结果。

• 继续完善程序：编写 Agent 程序
• 处理文件或返回下载结果：读取用户输入并返回结果
• 准备上线：准备发布

发布前仍需补齐 Agent 介绍、价格和资源设置，并完成正式用户入口复测。

已有环境或连接过期时，阅读连接云端开发环境，不要重复创建。

先确认开发工具可用，再开始创建环境或修改代码。文中命令来自官方开发工具；不同安装版本或环境提供的功能可能不同，以你当前看到的返回结果为准。

本机需要什么

oasn-sa-dev --version
oasn-sa-dev auth status
oasn-sa-dev doctor
oasn-sa-dev portal commands

本套文档按 oasn-sa-dev 0.6.0 编写。低于该版本时，历史版本来源选择、网页链接有效状态或刷新命令可能不可用；请按官方开发技能包更新，不改用自行拼接的接口。

各功能怎么确认

功能没有开放时

• 本包主要使用对话页面做开发测试，不提供开发版本的插件调用测试步骤。
• 本包不提供自行关闭云端环境的命令；需要释放环境时，使用官网实际提供的操作或联系支持。
• 某个查询返回 PORTAL_ENDPOINT_UNAVAILABLE，表示当前工具没有提供这项能力。不要自行拼接接口。
• 正式任务结束后的网页重开需要单独测试，不要据此承诺结果链接永久可用。

保留具体错误提示，有助于支持人员判断是工具版本、账号权限还是环境问题。

开发一个 OpenAgent，可以按“创建草稿 → 开发 → 测试 → 发布 → 维护”的顺序进行。

1. 创建草稿

一个 OpenAgent 可以有多个版本。草稿版本用于编辑程序、介绍和价格；已经发布的版本用于向用户提供服务。

开始修改前，确认当前是哪一个 Agent、哪一个版本，避免改错对象。

2. 在云端开发

云端开发环境提供 Linux、运行工具和对话页面。你可以上传业务代码、安装依赖、调试技能或插件。

环境和连接是两回事：环境可能仍在运行，但临时连接链接已经过期。此时恢复原环境的连接即可，不需要复制代码到一个新环境。

3. 检查真实效果

对话页面能打开，不代表程序能完成业务。用正常请求、文件输入和错误输入测试，并检查用户实际会拿到的结果。

4. 确认并发布

发布会让选定版本可供正式使用。提交后需要等待，请保存返回的发布编号并查询进度。

发布完成后，检查当前版本和上架状态，再从用户入口试用一次。

5. 维护和更新

需要改进时创建新的草稿版本。暂时不提供服务时暂停 Agent；要切回已确认的历史版本时使用版本切换操作。删除或退役与暂停不同，执行前务必确认影响。

查看更新与版本管理

在任何一步都可以查询

查询不会替你创建、发布或删除内容。卡住时先查看当前状态，避免重复提交同一操作。

查看进度查询方法

你负责把业务能力做对；平台提供运行和发布所需的基础工具。两者配合，才能让用户拿到可靠结果。

平台提供什么

你需要保证什么

• 介绍中承诺的功能确实能完成。
• 缺少输入或外部工具失败时，Agent 会清楚解释，不编造结果。
• 上传的资料和输出的文件不含密码、登录信息或无关用户数据。
• 业务所需模型、工具、资源和费用已经确认。
• 新版本仍能完成原来支持的主要任务。

上线前检查三次

1. 看回复：是否解决了用户的问题，而不只是“执行成功”。
2. 开文件：下载并打开，确认内容没有缺失。
3. 用网页：点击主要功能，验证数据、操作和错误提示。

平台显示“发布完成”不代表已经替你测试所有业务场景。保留未测试项目，逐项补齐后再对外承诺。

先确认是否已经有对应 Agent。Agent、草稿版本和云端开发环境分别创建，不要把其中一个编号当成另一个。

1. 查找现有内容

oasn-sa-dev portal agents --limit 20
oasn-sa-dev portal versions --agent-id <agent_id> --limit 20

列表可能不止一页，请继续使用返回的下一页标记查询。确认对象后再执行写操作。

2. 创建 Agent 或草稿

oasn-sa-dev portal agent-create --idempotency-key <本次创建的固定键> --confirm
oasn-sa-dev portal version-defaults --agent-id <agent_id>
oasn-sa-dev portal version-create --agent-id <agent_id> --idempotency-key <本次创建版本的固定键> --confirm

只运行你当前需要的动作。--idempotency-key 用来避免同一操作重复执行：一次创建使用一个固定字符串；网络中断后继续同一次操作时保留原值。

3. 导出草稿副本

oasn-sa-dev portal draft-export --version-id <agent_version_id> --output <临时目录>/draft.json

工具会生成可以保存的表单副本。不要把整个查询响应直接提交回去，也不要修改本地原始文件。

4. 修改并保存

oasn-sa-dev portal draft-save --version-id <agent_version_id> --body-file <临时目录>/draft.json --if-match <导出时返回的etag> --confirm

etag 是用于防止覆盖其他修改的版本标记，请原样使用，包括它本身的双引号以及可能存在的 W/ 前缀。为了避免 shell 去掉双引号，用单引号包住完整值：

--if-match '"draft-example"'
--if-match 'W/"draft-example"'

示例值不能用于真实保存。请复制本次导出结果中的原始 ETag；保存后重新查询，不继续使用旧标记，也不使用 *。

• 只修改你想改的部分，其余字段保留。
• 空数组可能表示清空内容，不表示“保持原样”。
• 收到 409 或 412 时，重新导出并比较差异，不强行覆盖。
• 网页端口通过独立端口命令设置，不塞入草稿表单。

草稿保存成功后，继续编写 Agent 程序或填写 Agent 介绍。

Agent 程序包括业务说明、技能、插件、源码和静态资源。先做一个能完成单个任务的小版本，再逐步添加文件处理、外部工具或交互网页。

文件放在云端 /oasn

/oasn/
├── AGENTS.md
├── SOUL.md
├── IDENTITY.md
├── USER.md
├── TOOLS.md
├── skills/<技能名>/SKILL.md
├── .openclaw/extensions/<插件名>/
├── service/
└── 业务源码和静态资源

只创建实际需要的可选目录。AGENTS.md 描述处理任务时需要遵守的业务规则；技能和插件用于增加可重复执行的流程或工具。

从 main 开始

用户请求默认交给名为 main 的 Agent。确保它能直接读取你的说明，并能使用需要的技能和插件。

你可以让它分配子任务，但不要只把功能配置给另一个 Agent，导致默认入口无法工作。

先约定输入与输出

写代码前回答三个问题：

1. 用户需要提供哪些文字或文件？
2. 成功后要得到文字、文件还是网页？
3. 缺少资料或工具不可用时，应该怎么回答？

查看输入与结果指南

验证依赖能运行

requirements.txt、package.json 只说明需要什么，不代表已经安装。请在云端实际导入依赖、运行脚本，并重启业务服务测试一次。

不要依赖本机路径，也不要把修改平台自带程序作为实现业务的方式。

保持交付目录干净

业务目录中不要混入密码文件、浏览器登录数据、历史对话、日志、缓存和临时测试数据。正式使用时，也不要依赖 BOOTSTRAP.md 这类只在首次初始化执行的文件。

云端发布还可能保留你在业务目录之外安装的系统包、全局依赖和自有文件。完成开发后，按发布前检查检查自己使用过的临时目录、缓存、日志和备份；不要假设平台会自动清洗整个开发环境。

云端开发环境用于安装依赖、上传程序和测试 Agent。命令中使用 workspace 表示这个环境，workspace_id 是它的编号。

创建新环境

先确认目标草稿版本编号，再查看是否已有环境以及可以从哪个历史版本继续：

oasn-sa-dev workspace sources --version-id <agent_version_id>

如果返回 existing_workspace，查询并续用该环境，不再创建。没有活动环境时，根据开发者确认的选择执行其一：

oasn-sa-dev workspace create --version-id <agent_version_id> --source-version-id <已确认的来源版本编号>
oasn-sa-dev workspace create --version-id <agent_version_id> --fresh

第一条从一个可恢复的已发布版本继续，第二条从基础环境开始。工具给出推荐来源时仍需你确认；有历史版本但未选择来源，不会创建环境。

工具会检查本机条件、完成登录并等待创建。缺少 SSH 公钥时，确认愿意创建后执行 oasn-sa-dev ssh-key ensure --create。

不要因为创建较慢就反复创建。超时后保留已返回的环境编号，继续查询即可。

继续查看已有环境

oasn-sa-dev workspace status --workspace-id <workspace_id>

连接前同时确认：

二者都满足后，使用工具返回的完整 SSH、SCP 命令和对话页面链接。不要自行改 host、端口、用户名或密钥参数。

链接过期怎么办

如果环境仍为 active，但连接是 expired，确认你仍要使用这个环境，再执行：

oasn-sa-dev workspace resume --workspace-id <workspace_id>

这会更新原环境的连接，不会新建环境、覆盖代码或更换你的 SSH 密钥。完成后重新确认 connection_status=ready，使用新返回的有效期和链接。

如果连接显示 unavailable，或环境已进入发布、关闭、清理过程，请停止连接并查看错误提示。

查看外部工具连接状态

环境摘要还可能返回 paid_api_mcp_status、paid_api_mcp_url 和到期时间。只有实际使用平台付费工具时才需要这些字段；状态不是 active 时，不要复制旧地址或改用个人密钥。

进入后从哪里开发

业务文件放在 /oasn。需要读取当前 Agent 和版本编号时，在云端执行：

bash -lc 'printenv OASN_AGENT_ID OASN_AGENT_VERSION_ID'

这两个值只用于帮助程序识别当前 Agent，不用于登录。若值为空，不要猜测或补写，先保留环境编号并联系支持。

环境账号可以使用 sudo 安装依赖，操作系统文件前请谨慎。日常开发尽量限制在业务目录。

让本地 AI 助手帮助修改代码时，先使用临时副本。这样可以保留你当前工作目录中的未提交修改，也方便上传前检查差异。

1. 复制本次需要的文件

macOS、Linux 或 WSL：

work_dir="$(mktemp -d "${TMPDIR:-/tmp}/oasn-sa-dev.XXXXXX")"
cp -p -- "<本地原文件>" "$work_dir/<文件名>"

Windows PowerShell：

$workDir = Join-Path ([System.IO.Path]::GetTempPath()) ("oasn-sa-dev-" + [guid]::NewGuid())
New-Item -ItemType Directory -Path $workDir | Out-Null
Copy-Item -LiteralPath "<本地原文件>" -Destination (Join-Path $workDir "<文件名>")

只修改副本，不覆盖原文件。上传前核对原文件摘要未变化。

2. 检查改了什么

git diff --no-index -- "<本地原文件>" "$work_dir/<文件名>"

这条命令发现差异时返回 1，不代表出错。继续运行文件对应的格式或语法检查，例如 JSON 校验、Python 编译检查或项目测试。

不要上传密码配置、浏览器数据、历史对话、日志、.git 或依赖缓存。优先传明确文件，不递归上传整个用户目录。

3. 确认环境和目标

先查询环境，确认 status=active 且 connection_status=ready。连接过期时先确认恢复原环境。

把要上传的文件、要覆盖的目标和差异展示给开发者，确认后再执行。使用工具返回的完整连接命令，不自行拼接地址。

4. 先暂存，再应用

把副本传到本次专用的暂存目录：

/oasn/.oasn-staging/<本次标识>/

在云端核对 SHA-256，确认传输内容一致后，再复制到明确的业务文件或配置路径。修改需要管理员权限的位置时，只在云端使用已确认的 sudo 操作。

5. 测试并清理

检查配置是否正确、服务能否运行，以及真实请求是否得到预期结果。只清理本次创建的临时副本和暂存目录，保留本地原文件不变。

先选择最简单的扩展方式。不要为了一个固定流程同时引入技能、插件和外部服务。

选择扩展方式

技能放在 /oasn/skills/<技能名>/；插件放在 /oasn/.openclaw/extensions/<插件名>/。外部工具连接配置写在 openclaw.json 的 mcp.servers 中。

添加插件

按插件本身的安装说明操作。如果它要求从本地目录建立安装记录，可以使用：

openclaw plugins install --link /oasn/.openclaw/extensions/<插件名>

安装后检查：

openclaw plugins list
openclaw plugins inspect <插件名> --runtime --json
openclaw plugins doctor

需要重启 OpenClaw 对话服务时，按当前官方开发技能包中的重启步骤操作。不要启动第二个服务，也不要使用强制终止进程的方式解决配置问题。

连接外部工具

遵循你使用的 OpenClaw 版本和服务提供方的配置说明。工具名称和参数以当次发现的列表为准，不从旧文档猜测。

在对话页面执行一次真实业务请求，确认 Agent 选择了正确工具、填写了正确参数，并理解了返回结果。

使用平台提供的付费 API

先查询当前环境，确认 paid_api_mcp_status=active，并读取本次返回的 paid_api_mcp_url 和到期时间。不要从历史记录或其他环境猜地址。

得到开发者确认后，在同一个云端环境中保存平台保留连接。把下面的地址占位替换为本次查询值；单引号必须保留：

sudo -n openclaw mcp set oasn-paid-api '{"enabled":true,"transport":"streamable-http","url":"<本次返回的paid_api_mcp_url>","headers":{"Authorization":"Bearer ${OASN_PAID_API_MCP_TOKEN}","X-OASN-MCP-Auth-Mode":"OASN_DEVELOPER"}}'

认证由云端受管进程持有。不要读取进程环境、复制变量值，或把令牌写入命令、配置文件和日志。

使用受控命令查看当前工具：

sudo -n oasn-paid-mcp probe
sudo -n oasn-paid-mcp tools --include '<工具名>'

第二条命令只保留业务需要的工具。名称必须来自本次探测，明确、唯一且不能使用通配符；保存后再次探测确认。

命令提示凭据缺失或过期时，停止调用。只有在你确认继续使用原环境后，才运行 workspace resume 更新该环境；不要改为个人长期密钥或直接运行不带受控环境的探测命令。

检查是否真的可用

配置保存成功、工具出现在列表里，都还需要一次实际调用来验证。失败时说明原因；不要无限重试、改用个人长期密钥，或编造外部服务没有返回的数据。

调用付费工具可能产生费用，避免重复请求和没有上限的并行调用。

先确定任务需要哪些能力，再选择模型。例如纯文本助手需要聊天模型，图片理解、图片生成、语音或 PDF 处理可能需要额外能力。

1. 查看可选项

oasn-sa-dev portal models --version-id <agent_version_id>
oasn-sa-dev portal resources
oasn-sa-dev portal resource-config --version-id <agent_version_id>

使用当前查询返回的选项编号，不用展示名称代替。模型是否可选、价格和限制都以当前结果为准。

2. 保存模型选择

工具使用以下字段区分不同用途：

在临时 JSON 副本中保留完整选择，未选择的可选项用 null。不要因为只换一个模型而清空其余字段。

oasn-sa-dev portal models-save --version-id <agent_version_id> --body-file <临时目录>/models.json --if-match <当前etag> --confirm

--if-match 必须保留 ETag 自带的双引号，具体引用方式见命令速查。

3. 保存 CPU 和内存

临时 JSON 使用 cpu_resource_id 和 memory_resource_id，值来自资源查询结果。

oasn-sa-dev portal resources-save --version-id <agent_version_id> --body-file <临时目录>/resources.json --if-match <当前etag> --confirm

每次保存后重新查询。保存表单不表示已有开发环境已经扩容或重建，请检查环境摘要，并按需要重新测试。

4. 重新测试并查看费用

模型变化可能改变回复质量、速度和费用。用代表性请求重测，不仅检查能否连接。

发布后使用平台提供的模型设置，开发时自行填写的地址和密钥不会原样保留。如果你需要的某项能力不可用，请先解决选择问题再发布。

了解发布后哪些设置会变化

开发时先约定用户需要给什么，以及完成后能拿到什么。让缺少输入和失败的情况也有清晰回复。

先区分两种测试入口

开发对话页不保证创建正式调用的 JSON 文件。不要因为对话测试成功就假设脚本已经读过该文件，也不要在开发环境中读取遗留文件冒充本次输入。

正式调用时读取结构化输入

正式调用进入 main 时，如果业务脚本需要自己读取原始输入，可以使用：

/oasn/in/invocation.json

其中 input.user_prompt 是用户文字，input.attachments 提供本次附件路径。只依赖这两个公开字段，不读取调用编号、计费信息或其他平台字段。

只读取这些明确给出的文件，不扫描旧目录或复用上次任务的文件。

在开发环境测试输入解析器

让解析器接受“输入文件路径”参数。开发测试时，在自己的测试目录准备一个同结构样例；正式运行时再使用 /oasn/in/invocation.json。不要手工创建或覆盖平台的 /oasn/in/invocation.json。

最小样例：

{
  "schema_version": "oasn.invocation.v1",
  "input": {
    "user_prompt": "请总结附件内容",
    "attachments": ["/oasn/testdata/example.txt"]
  }
}

先用测试文件验证正常输入、空附件和缺少必要文字，再到开发对话页验证 main 的实际回复。发布后还要从正式入口完成一次文件请求。

返回文字

最终回复应直接回答用户的问题。信息不足时指出缺少什么；工具失败时说明本次没完成的部分。

不要把运行日志、密码、调试详情或没有依据的内容作为结果。

返回文件

1. 在业务目录中生成真实文件。
2. 在最终回复中添加文件附件或 Markdown 链接。
3. 从对话页面点击下载，并实际打开检查。

只回复 /oasn/... 这样的路径，用户无法据此取得文件。

返回交互网页

如果结果需要筛选、编辑或展示图表，可以增加业务网页。页面服务必须使用你声明的端口，再通过规定格式返回链接。

为结果添加交互网页

转交文件给其他 Agent

自己的本地路径不是另一个 Agent 能读取的地址。请使用平台返回的附件对象；新生成的文件先通过当前提供的文件登记能力取得附件对象，不自行拼接引用。

文件链接不是永久存储

开发环境中的下载链接会过期，环境关闭或发布后也可能失效。需要保留的测试结果请及时下载。发布完成后，重新执行正式任务检查用户收到的文件，不把开发时的临时链接写进介绍。

当文字或文件不够表达结果时，可以让 OpenAgent 返回交互网页，例如报告、图表或编辑界面。平台提供访问链接，你负责网页本身的功能和数据。

1. 启动你的网页服务

选择一个业务端口，让服务监听 0.0.0.0:<端口>。网页采用什么框架、如何组织源码，由你决定。

页面资源、API 和 WebSocket 应根据 window.location 使用相对地址，避免写死本机、云端内网或其他环境的地址。

2. 声明使用的端口

oasn-sa-dev version webui-ports get --version-id <agent_version_id>
oasn-sa-dev version webui-ports set --version-id <agent_version_id> --ports 7860,8765

--ports 会替换完整列表，不是追加。取消全部网页端口时，确认后使用 --clear。

端口需为不同的 1..65535 整数，不能使用平台保留的 22、18789、18790。

3. 等待配置和链接都可用

继续查询端口状态，只有下面两项同时满足才使用返回的 webui_urls：

两项就绪仍不表示你的网页服务已启动或功能正确。修改端口会更新链接，旧链接不再使用；保存端口不会替你启动网页服务。

如果仍在 pending，只继续查询，不再次设置或刷新。not_configured 表示没有声明端口，unavailable 表示当前无法确认链接有效性；后两者都不能交付旧链接。

4. 链接过期或撤销时刷新

先查询开发环境状态：

• 环境仍为 active，但 connection_status=expired：确认继续使用原环境后，先运行 workspace resume。
• 环境连接仍为 ready，但网页 proxy_status=expired 或 revoked：确认需要新链接后执行：

oasn-sa-dev version webui-ports refresh --version-id <agent_version_id>

刷新保留完整端口列表和云端文件，不清空端口，也不新建环境。不要用重复 set、先 --clear 再恢复，或重新登录来代替刷新。命令超时或出现冲突时，先用 get 查询当前结果，不自动重复刷新。

5. 在最终回复中返回网页

每个页面使用一个代码块，标记必须是 oasn-webui：

```oasn-webui
{"type":"webui","title":"分析结果","url":"http://127.0.0.1:7860/results","defaultOpen":true}
```

只包含 type、title、url、defaultOpen 四个字段。内部 URL 的端口必须已经声明，平台会将它转换为用户可以访问的地址。

多个页面最多一个 defaultOpen=true。这个值表示希望客户端优先打开哪个页面，不表示页面已通过测试，也不保证客户端一定自动打开。

6. 实际测试

逐个检查页面内容、按钮、业务 API、静态资源和 WebSocket。链接可打开不代表功能正确。

任务结束后能否重新打开结果页也要单独验证。没有成功测试前，不承诺链接永久有效；使用平台当前返回的结果链接，不保存或拼接临时代理地址。

你的 Agent 可以专注于组织结果，把专业分析或生成工作交给其他 OpenAgent。只有当前工具列表实际提供 openagent_agent_run 时，才使用这项能力。

1. 确认目标和输入

目标编号来自本次搜索或选择结果。先看它接受什么输入、会返回什么，以及可能产生的费用。

{
  "agent_id": "<目标Agent编号>",
  "idempotency_key": "<本次任务的固定键>",
  "data": {
    "prompt": "请完成这项具体任务"
  }
}

data 中只填目标工具允许的业务参数。不要自己传价格、付款人、目标版本或平台管理的参数。

2. 避免重复执行

idempotency_key 用来识别同一次任务。网络中断后确认需要继续同一次操作时，保持键值和输入不变。结果未知时先查询或说明不确定，不换键重复执行。

只有继续之前的对话时，才使用先前结果返回的 agent_session_id，不要自己生成这个值。

3. 传递文件

已有附件对象可以直接转交。新文件先使用当前环境提供的文件登记能力；不要把自己环境里的路径、任意网盘地址或图片编码当作附件对象。

4. 读取结果

按这个顺序判断：

1. isError：是否返回错误。
2. structuredContent.status：目标任务是否真正完成。
3. content：文字、文件、图片或音频。
4. structuredContent.views：可选的交互网页。

有返回值不一定表示成功。目标失败、取消或超时时，向用户说明未完成内容，不编造目标 Agent 的答案。

5. 保持调用有限

每次调用都可能收费。避免循环调用、无限重试和没有上限的并行任务。最多支持 8 层调用，子任务还会受到当前任务剩余时间限制。

查看组合示例

好的介绍不是功能清单，而是帮助用户判断“这个 Agent 能不能完成我的任务”。

写清五件事

• 适合做什么：用具体任务描述，而不是“能力强大”。
• 需要什么输入：文字、文件格式和必要信息。
• 会得到什么：摘要、文件、图片或交互网页。
• 怎样使用：给出一个简短的请求示例。
• 有哪些限制：不能做的事、数据范围或需要用户确认的操作。

不要写尚未实现或没有测试过的功能。

保存介绍

先导出草稿副本，再修改其中的 agent_card 字段：

oasn-sa-dev portal draft-export --version-id <agent_version_id> --output <临时目录>/draft.json
oasn-sa-dev portal categories
oasn-sa-dev portal draft-save --version-id <agent_version_id> --body-file <临时目录>/draft.json --if-match <原始etag> --confirm

保存完整表单，保留程序设置和价格。分类与标签使用工具当前返回的编号，不堆叠无关标签增加曝光。

--if-match 使用导出结果中的原始 ETag，并保留值本身的双引号；终端引用方式见命令速查。

上传使用说明与图片

平台把使用说明称为 MOM。上传 Markdown 时，至少包括 Use when、Inputs、Outputs 三个小节：

oasn-sa-dev portal mom-upload --file <临时目录>/MOM.md --idempotency-key <固定键> --confirm
oasn-sa-dev portal image-upload --purpose agent_card_avatar --file <已确认的图片> --idempotency-key <固定键> --confirm

Markdown 为非空 UTF-8 文件，大小不超过 1 MiB。图片支持 PNG、JPEG、WebP，不超过 5 MiB。

上传成功会返回素材编号，仍需要把它保存到草稿。不要把本地路径或临时预览地址直接写进公开介绍。

程序变化时同步更新

支持的输入、输出、网页或限制发生变化后，重新检查介绍。最好的检验方式是让第一次看到介绍的人，能给出一个有效请求并理解预期结果。

定价由你决定。本地 AI 助手可以整理信息、检查字段，但不应替你选择利润率或在未确认时修改价格。

1. 先看成本

oasn-sa-dev portal direct-costs --version-id <agent_version_id> --scope configured
oasn-sa-dev portal direct-costs --version-id <agent_version_id> --scope observed

configured 用于查看已选择资源对应的成本；observed 用于查看已有测试用量的估算。

保留返回的单位、时间和金额。没有观测数据不表示零成本，也不能用估算结果推算实际收入。

2. 确认收费字段

当前示例使用按成本加价的方式：

可选范围和最终校验以官网返回为准。不要自行修改平台显示的只读费用。

3. 保存并检查

在临时草稿中修改 pricing，然后保存完整表单：

oasn-sa-dev portal draft-export --version-id <agent_version_id> --output <临时目录>/draft.json
oasn-sa-dev portal draft-save --version-id <agent_version_id> --body-file <临时目录>/draft.json --if-match <原始etag> --confirm

--if-match 使用导出结果中的原始 ETag，并保留值本身的双引号；终端引用方式见命令速查。

保存后重新查看版本和发布前检查。确认 CPU、内存和所需模型已配置。

提防意外费用

外部付费工具和其他 OpenAgent 调用可能另行产生费用。限制重试次数和并发数量，避免对同一请求重复执行。价格或使用限制变化后，记得更新 Agent 介绍。

使用开发工具返回的对话页面测试，不需要先发布 Agent。连接前确认 status=active 且 connection_status=ready；链接过期时先确认恢复原环境。

至少测试三类请求

1. 正常请求：用户提供了完整信息，应该得到正确结果。
2. 文件请求：上传一个支持的文件，确认能读取和处理。
3. 边界请求：缺少资料、格式不支持或工具不可用，应该清楚说明原因。

按结果逐项检查

端口设置更新后，用新返回的网页链接测试；不要继续使用失效的旧地址。

不要用这些结果代替业务测试

安装命令没有报错、程序进程存在、网页可以打开或工具出现在列表中，都不表示任务一定能完成。

记录未测试内容

写下已测试的请求、实际结果和仍未检查的功能。这些记录可以帮助你准备发布，也能在问题发生后重现。

本包以对话页面作为开发测试入口。发布完成后，还应从官网当前提供的正式使用入口再次验证，不把开发页面的结果当成用户已能使用。

对话页面会把消息和附件交给 main，但不保证生成正式调用使用的 /oasn/in/invocation.json。业务脚本依赖该文件时，还要按输入与结果指南使用测试样例验证解析器，并在发布后完成正式文件请求。

把下面的项目逐项检查。没有测试过的内容就写明未测试，不要默认通过。

Agent 能否完成任务

• 默认 main Agent 可以使用全部主要功能。
• 一次完整的正常请求得到正确且非空的回复。
• 缺少资料时会说明需要补什么。
• 外部工具失败时会说明未完成部分，不编造数据。
• 依赖、脚本和业务服务在云端实际运行过。

用户能否拿到结果

• 文件可以下载并打开，内容完整。
• 网页中的主要按钮和数据展示正确。
• 页面资源和接口使用相对地址。
• 修改或刷新网页端口后，已同时确认 sync_status=ready、proxy_status=ready，并测试新链接。
• 多个结果页面最多只选择一个默认打开。

使用的扩展是否有效

• 每个技能在适合的请求中确实被使用。
• 每个插件已经加载，并完成一次实际工具调用。
• 外部工具参数符合当前说明，没有多传、漏传。
• 所需模型能力已选择，并用代表性输入测试。

公开介绍与价格是否准确

• 名称、简介和分类与真实功能一致。
• 使用说明解释了输入、输出和限制。
• 没有宣传尚未实现的功能。
• 图片和资料有权使用，没有临时预览链接。
• 价格由你确认，模型和运行资源已保存。

数据是否安全

• 没有上传密码、登录信息、私钥或浏览器数据。
• 没有把历史对话、日志或他人的文件作为业务结果。
• 本地修改在副本中完成，原文件没有被覆盖。
• 已检查 /oasn、/tmp、个人下载目录、shell 历史、工具缓存、自建日志、备份和数据库中自己创建的内容。
• 临时测试数据已经按需要下载或清理；没有批量删除归属不明的系统文件。
• 明白云端安装的系统包、全局依赖和业务目录之外的自有修改也可能进入正式版本。

运行发布前检查

oasn-sa-dev portal readiness --version-id <agent_version_id>
oasn-sa-dev version webui-ports get --version-id <agent_version_id>

处理工具报告的问题，并再次查询。工具检查通过后，仍由你确认业务效果，才进入发布。

遇到问题先保留当前 Agent、版本、环境或发布编号，以及错误提示。不要为了“再试一次”立刻创建另一个环境或提交新的发布。

每条命令都让我重新登录

先运行 oasn-sa-dev auth status。检查系统密码管理器是否已解锁，并允许开发工具保存登录会话。

如果看到 CREDENTIAL_STORE_WRITE_FAILED、CREDENTIAL_STORE_VERIFY_FAILED 或 CREDENTIAL_STORE_UNAVAILABLE，先解决密码管理器问题。刚才的业务操作可能已经成功，不要重复执行，也不要把登录信息保存到普通文本文件。

创建环境等了很久

保留已返回的 workspace_id，继续查询：

oasn-sa-dev workspace status --workspace-id <workspace_id>

WORKSPACE_TIMEOUT 表示本次等待超时，不一定表示创建失败。不要同时运行多条查询或反复创建。

环境还在，链接却打不开

查看 connection_status：

• expired：连接过期，确认继续使用原环境后运行恢复命令。
• unavailable：连接信息暂不可用，保留提示并联系支持。
• ready：使用这次返回的完整链接，而不是旧收藏地址。

oasn-sa-dev workspace resume --workspace-id <workspace_id>

环境已经发布、关闭或正在清理时，不要继续尝试连接。

插件装好了，但 Agent 不使用

openclaw plugins inspect <插件名> --runtime --json
openclaw plugins doctor

确认安装说明已完成，并按官方开发技能包重启 OpenClaw 对话服务。再给出一个明确需要该插件的请求。不要另起第二个服务或直接强杀进程。

工具找不到或返回错误

只使用当次列出的工具名称和参数。确认地址和所需环境配置来自当前开发环境，不用旧值或个人密钥替代。工具可能已经产生费用时，不自动重复调用。

网页链接有了，但内容不正常

先运行 webui-ports get。sync_status=ready 只表示端口声明已同步，只有 proxy_status=ready 才返回当前有效链接；两者都就绪仍不表示网页程序正确。

• 502：先检查业务服务是否监听已声明端口，以及相对路径、静态资源和 API 是否正确。
• expired：先判断开发环境连接是否也过期；环境过期需经确认运行 workspace resume。
• revoked，或只有网页链接过期：经确认运行 webui-ports refresh，不要清空端口或重复设置相同列表。
• unavailable：保留提示并检查工具或服务版本，不复用旧链接。

保存时出现 409 或 412

别人或另一次操作可能已经修改了草稿。重新导出最新内容、比较差异，再确认要保存什么。不要用通配符或旧版本标记强行覆盖。

提交后不知道有没有成功

出现 PORTAL_RESULT_UNKNOWN 或网络断开时，先查询原来的对象或发布编号。保留原固定键和输入，不换键重复提交。

某项功能提示不可用

PORTAL_ENDPOINT_UNAVAILABLE 表示当前开发工具没有开放这项能力。查看官网实际提供的功能或联系支持，不自行拼接口。

联系支持时提供什么

提供发生时间、操作步骤、相关编号、错误码和 request_id。不要发送密码、访问令牌、浏览器登录信息或未脱敏的用户资料。

发布前先做最后一轮检查。发布可能结束当前开发连接，请提前下载需要保留的测试结果。

1. 确认发布的是哪个版本

oasn-sa-dev portal version --version-id <agent_version_id>

检查 Agent 名称、版本编号和是否可编辑。不要仅凭旧页面、相近名称或历史链接决定目标。

2. 完成用户场景测试

至少检查一个正常请求、一个文件请求和一个边界请求。直接打开生成的文件、操作结果页面。

使用上线前自检清单

3. 核对介绍和收费

• 介绍中写的输入、输出和限制与程序一致。
• 所需模型、CPU 和内存已选择。
• 价格已由你确认。
• 需要的外部工具至少实际使用过一次。
• 没有密码、浏览器数据或无关测试文件。

4. 检查网页端口

oasn-sa-dev version webui-ports get --version-id <agent_version_id>

使用业务网页时，等待 sync_status=ready 和 proxy_status=ready，再测试新链接。仍在 pending 时继续查询；expired 或 revoked 按网页指南恢复，不能只凭端口同步完成发布。

5. 检查将进入正式版本的内容

发布保存的不只是你在 /oasn 中看到的源码。云端环境里由你安装的系统包、全局依赖、业务文件和其他自有修改，也可能进入正式版本；平台不会扫描并清理所有自定义位置。

发布前逐项检查你自己创建的内容：

• /oasn 中的测试输入、临时输出、备份、日志和本地配置。
• /tmp、个人下载目录、浏览器资料、shell 历史及 npm、pip 等工具缓存。
• 自建数据库、诊断目录、后台服务写入的数据，以及业务目录之外的文件。
• 源码、构建产物和配置中是否残留密码、令牌、Cookie 或用户资料。

只处理你能确认归属并且确定不再需要的内容。不要批量删除系统目录或平台提供的文件；不确定时先保留并联系支持。

6. 执行发布前检查

oasn-sa-dev portal readiness --version-id <agent_version_id>

工具会报告仍缺少的设置。修正后再次查询；没有阻断项不表示所有业务场景都已替你测试。

7. 确认再发布

只清理你自己创建、确定不再需要的临时内容。不要删除平台自带文件。确认功能、价格和目标版本后，继续发布你的 Agent。

发布前先完成准备发布。如果由本地 AI 助手执行，先让它说明目标版本和影响，再由你确认。

1. 提交发布

oasn-sa-dev portal publish --version-id <agent_version_id> --idempotency-key <本次发布固定键> --confirm

一次发布使用一个固定键。默认不需要额外正文；只有当前工具要求并提供了真实验证编号时，才按它的说明填写。

保存返回的 publish_job_id，接下来查询这个编号，不重新提交。

2. 等待完成

oasn-sa-dev portal publish-job --publish-job-id <publish_job_id>

发布需要时间。202 表示已经开始处理，进度百分比不是剩余时间。工具要求继续等待时，按返回的间隔查询。

不要因为页面可见或进度到 90% 就关闭等待，仍可能有后续步骤未完成。

3. 核对结果

确认工具显示发布成功，目标版本与返回的 published_version、current_version 一致。随后检查 Agent 是否已经上架；发布版本和开放服务可能是两个操作。

4. 从用户入口再试一次

确认可能产生的费用后，发起一个代表性任务。检查用户是否能收到正确回复，下载文件并打开网页。

开发环境中的临时结果不能替代正式使用结果。

失败或网络中断

保留发布编号、固定键、错误提示和请求编号。先查询原来的发布结果，不换参数重新发布。需要修正内容时，确认草稿当前是否仍可编辑。

常见问题与解决方法

云端开发环境允许你尝试不同配置，但正式用户不会使用你的个人开发环境。发布前请确认程序不依赖临时链接、个人登录信息或本机设置。

正式运行使用平台提供的模型

开发时试用的模型地址和密钥不会原样成为正式配置。你需要在平台提供的选项中选择业务所需能力，并确认测试效果。

文字、图片、视频、语音和 PDF 处理的模型能力可能不同。某项必需能力没有可用选项时，请先调整选择或联系支持，不要直接删掉功能后仍宣传它可用。

不要依赖个人登录信息

不要把模型密钥、浏览器登录数据或临时授权写进源码。外部工具请使用当前开发流程提供的连接方式；发布后仍需验证工具可用。

如果业务代码自己连接外部服务，费用、权限和可用性需要你单独确认。

开发链接可能结束

发布后，原来的 SSH、对话页面、临时下载和网页预览链接可能失效。不要把这些地址写在 Agent 公开介绍里。

正式结果应由用户发起任务后取得，请用正式入口再测试一次。

平台自带程序会按正式环境准备

业务代码放在自己的目录。不要通过替换平台自带的 OpenClaw 程序来实现功能，也不要依赖历史对话、调试日志或一次性初始化文件。

发布后复查

• 回复质量和开发测试时是否一致。
• 必需模型和外部工具能否完成任务。
• 文件是否真实可下载。
• 网页是否在用户当前结果链接中工作。
• 失败时是否给出清晰说明。

关掉本地终端或对话页面，不会自动释放云端开发环境。先确认你是想暂时离开、恢复连接，还是不再保留环境。

暂时离开

可以关闭本地窗口。以后继续时先查询原来的环境，不必马上创建新的。

连接过期但还要继续开发

查询结果仍为 status=active，连接为 expired 时，确认继续使用原环境后执行：

oasn-sa-dev workspace resume --workspace-id <workspace_id>

使用新返回的连接信息。恢复连接不会重新上传代码，也不会新建环境。

取消一个开发连接

官网或工具可能提供撤销技能连接的操作。撤销连接不一定删除开发环境；如果结果显示 sandbox_retained=true，表示环境仍保留。

不要把“链接不可用了”理解成“资源已经释放”。

不再保留环境

本包不提供自行拼接关闭接口的命令。使用官网当前实际提供的关闭操作；没有该入口时，提供环境编号联系平台支持。

需要保留的业务文件先安全下载，不要导出登录信息或浏览器数据。

发布过程中

发布可能结束开发环境的使用。看到 close_pending 或 cleanup_pending 时继续等待或联系支持，不强行删除进程，也不创建新环境掩盖原来的问题。

查询明确显示 closed 或 published 后，不再使用旧开发链接。

不知道下一步该做什么时，先查询当前状态。查看信息不会替你创建、修改或发布 Agent。

查看 Agent 和版本

oasn-sa-dev portal agents --limit 20
oasn-sa-dev portal versions --agent-id <agent_id> --limit 20
oasn-sa-dev portal version --version-id <agent_version_id>

列表不一定只有一页。继续使用当前返回的 next_cursor 查询时，保持筛选和排序不变。

查看开发环境

oasn-sa-dev portal sandbox --agent-id <agent_id>
oasn-sa-dev workspace status --workspace-id <workspace_id>

第一个命令查看 Agent 关联的开发环境摘要，第二个命令查看具体环境及连接状态。

连接可用需要同时满足 status=active 和 connection_status=ready。如果连接过期但环境仍在，确认继续使用后再恢复原环境连接。

查看网页端口

oasn-sa-dev version webui-ports get --version-id <agent_version_id>

sync_status=pending 时继续查询，不重复设置。只有 sync_status=ready 且 proxy_status=ready 时才使用新链接；这仍不表示网页业务已经健康。

如果 proxy_status=expired 或 revoked，先确认开发环境仍为 active。环境连接过期时先恢复连接；只有网页链接失效且你确认需要新链接时，才使用 version webui-ports refresh。unavailable 时保留提示，不交付缓存中的旧 URL。

查看发布进度

oasn-sa-dev portal publish-job --publish-job-id <publish_job_id>

使用提交发布时返回的编号。按照 poll_after_ms 建议的间隔等待；超出本次等待时间时保留编号，之后继续查询即可。

几种编号不要混用

编号请从当前返回结果取得。不要因为名称相同，就默认它是你要修改的对象。

先决定你想改变什么。暂停使用、下线一个版本、切回旧版和不可恢复退役的影响不同，不要连续执行一组写命令。

更新功能

为已有 Agent 创建新的草稿版本，完成开发测试后再发布。不要直接把正式用户正在使用的内容当作临时试验环境。

创建 Agent 和草稿版本

上架或暂停 Agent

在临时 JSON 中填写 {"supply_status":"listed"} 或 {"supply_status":"suspended"}：

oasn-sa-dev portal supply-status --agent-id <agent_id> --body-file <临时目录>/supply.json --idempotency-key <本次固定键> --confirm

前者开放服务，后者暂停服务。暂停不等于删除 Agent 或它的历史版本。

下线指定版本

oasn-sa-dev portal version-suspend --version-id <agent_version_id> --idempotency-key <本次固定键> --confirm

如果工具报告仍有使用或依赖冲突，先处理提示，不强制绕过。

切回历史版本

先查询版本列表，确认目标属于同一个 Agent。在临时 JSON 中填写：

{"target_version_id":"<已确认的历史版本编号>","reason":"<切换原因>"}

oasn-sa-dev portal rollback --agent-id <agent_id> --body-file <临时目录>/rollback.json --idempotency-key <本次固定键> --confirm

这会改变后续用户使用的版本，不会把你的本地代码恢复到旧版本。完成后重新查询当前版本和上架状态。

不可恢复地退役

只在确定不再保留该 Agent 时考虑。退役与临时暂停不同，不可恢复；历史记录仍保留。

确认影响后，临时 JSON 的 confirmation 必须准确填写目标 agent_id：

oasn-sa-dev portal agent-retire --agent-id <agent_id> --body-file <临时目录>/retire.json --idempotency-key <本次固定键> --confirm

不要让本地 AI 助手自动确认或批量退役。

排错的目标是知道“哪一步没有得到预期结果”。先说明用户做了什么、应该得到什么，再看错误和日志。

先定位现象

• 不能登录或每次都要重新登录。
• 开发环境没有准备好。
• 对话无回复或回复不正确。
• 外部工具失败。
• 文件不能下载或内容不对。
• 网页打不开，或者按钮和数据出错。
• 发布长时间未完成。

查看常见问题

保存这些信息

分享输入时使用可以公开的测试数据；不要提交用户原始敏感资料。

查看业务日志

只有开发环境和连接都可用，并确认需要连接后，才查看自己的业务日志。日志可以帮助发现依赖缺失、配置错误和服务启动失败，但最终仍要重跑用户请求确认修复。

不要输出完整登录信息、密钥或浏览器数据。

查看调用统计

oasn-sa-dev portal metrics --agent-id <agent_id> --from <开始时间> --to <结束时间> --granularity day --timezone Asia/Shanghai

可以增加 --version-id。注意统计的时间范围、更新时间和单位；缺失或延迟数据不等于零。

提交给支持人员

用最短步骤描述问题，并附上经过检查的错误信息。不要发送整个环境配置、密码文件或浏览器存储。

用量告诉你 Agent 被使用了多少；成本估算帮助你判断模型和资源开销；实际收入和可提现金额需要查看账单。它们不能互相替代。

查询调用统计

oasn-sa-dev portal metrics --agent-id <agent_id> --from <开始时间> --to <结束时间> --granularity day --timezone Asia/Shanghai

时间使用 YYYY-MM-DD 或包含时区偏移的完整时间。可以增加 --version-id 单独查看某个版本。

显示结果时保留单位和更新时间。没有返回的值不补成零。

查询成本估算

oasn-sa-dev portal direct-costs --version-id <agent_version_id> --scope configured
oasn-sa-dev portal direct-costs --version-id <agent_version_id> --scope observed

配置成本与测试实际产生的观测成本可能不同。看到 no_usage 表示还没有对应观测数据，不是免费或零成本。

外部付费工具和其他 Agent 的调用可能另外收费。测试后再检查总成本，避免只看主模型价格。

查看收入和账单

以当前官网提供的账户与账单数据为准，不用调用次数、定价百分比或本地计算推算可提现金额。

如果工具返回 PORTAL_ENDPOINT_UNAVAILABLE，说明当前版本没有提供这项查询。不要填写估算余额或自行访问未公开接口。

调整收费前

先看一组代表性任务的耗时、效果与费用，再决定价格。收费变化由你明确确认，并同步更新用户可见的介绍和限制。

oasn-sa-dev 是 OpenAgent 的官方开发命令行工具。本套文档按 0.6.0 编写；先安装官方开发技能包中提供的版本，并用安装结果返回的绝对路径确认实际版本。

查看帮助

oasn-sa-dev --version
oasn-sa-dev portal commands
oasn-sa-dev portal <命令> --help

工具提示参数与本页不一致时，以当前安装版本的帮助和官网说明为准。

常用命令

创建、恢复连接、保存或发布都可能产生修改，请先确认对象和影响，不把表格中的命令当作一组连续执行的脚本。

登录信息怎么处理

工具会打开浏览器登录，并尝试在系统密码管理器中保存有效会话。你不需要手工提供访问令牌或读取浏览器登录信息。

密码管理器不可用时，不要改为普通文件保存。退出登录后查看工具是否同时完成账号会话退出与本地删除。

常见参数是什么意思

不要把这些参数套用到所有命令。网页端口设置使用 --ports 或 --clear，具体以它自己的帮助为准。

--if-match 的值必须保留服务返回的双引号。为了避免 shell 去掉引号，用单引号包住整个值，例如：

--if-match '"draft-example"'
--if-match 'W/"draft-example"'

以上只是格式示例。实际保存必须使用本次查询返回的完整 ETag，不能使用示例值、旧值或 *。

读取命令返回

http_status 是请求状态，data 是返回内容，request_id 可帮助支持人员定位问题。错误时保留 error_code 和 error_name。

请求显示受理后仍需等待业务完成；结果未知时先查询，不换固定键重复提交。

云端环境用来验证 Agent 在实际 Linux 环境中的运行效果。不要假设你本机安装的软件在云端也存在。

基础规格

具体版本和资源以当前开发工具返回的环境摘要为准。需要更多资源时，先查看平台可选项，不把基础配置当作自动扩容承诺。

常用软件

环境提供 Git、OpenSSH、Node.js 和 Python。其他依赖需要明确安装并运行测试。

例如可以在云端检查：

node --version
python3 --version
openclaw --version

版本输出只是环境信息，业务是否可用还要实际运行脚本和请求。

开发目录

业务文件放在 /oasn；OpenClaw 主配置位于 /root/.openclaw/openclaw.json。

查看文件放置说明

管理员权限

连接账号 developer 可以使用 sudo 安装依赖。这个权限能够改动系统文件，请谨慎操作；日常业务代码应留在自己的目录，不替换平台自带程序。

连接和过期

环境仍在不代表连接链接一直有效。只在 status=active 且 connection_status=ready 时使用当前连接；链接过期后确认恢复同一个环境，不自行猜测新地址。

先把文件分成三类：业务程序、运行配置、临时内容。只交付前两类中真正需要的文件，不把开发机器或云端环境整个复制出去。

云端开发时

不要把临时输入和输出当作源代码长期保存。

导出或交付包

使用平台提供的包导入、导出流程时，配置和业务文件按下列结构分开：

<包目录>/
├── package.json
├── agent-plugin/
│   └── openclaw/
│       ├── openclaw.json
│       └── workspace/
└── service/

• workspace/ 对应云端的 /oasn 业务内容。
• openclaw.json 保存需要交付的 OpenClaw 配置。
• service/ 可选，用于开发者自有网页、API 或文件服务。
• package.json 描述名称、使用说明和网页端口等包级信息。

Python、Node.js 服务应提供相应依赖说明。不要只打包依赖清单而不测试实际安装和启动。

交付包不等于正式环境的全部内容

上述目录是导出、审计和迁移时使用的包结构。通过云端开发环境发布时，正式版本还会保留你在平台管理目录之外安装的系统包、全局依赖、业务文件和其他自有修改。

因此，不能只检查包目录。发布前还要检查 /tmp、个人目录、工具缓存、shell 历史、自建日志、备份和数据库等自己使用过的位置。平台会处理已知的运行临时状态，但不会替你清洗任意自定义文件。

不要从本机上传 node_modules 或虚拟环境。业务实际需要的依赖应在云端安装并完成启动、重启测试；发布清理时不要删除正式运行仍需使用的云端依赖。

不应该进入交付包

• 密码、访问令牌、私钥、.env 和浏览器登录数据。
• 历史对话、日志、进程编号文件和临时测试数据。
• node_modules、本机虚拟环境和下载缓存。
• 运行时生成的认证数据库、models.json 等缓存状态。
• 平台自带程序的私有副本或开发时修改。

只有业务需要的目录才保留。不认识的文件先确认用途，不批量删除整个系统目录。

下面保留命令中真实出现的字段和错误名称，方便你对照屏幕。你不需要了解平台内部处理步骤。

开发环境状态

连接状态

active + expired 时，经你确认继续使用原环境后运行 workspace resume。该命令与只读的 workspace status 不同。

网页端口设置

端口声明和网页链接使用两组状态：

502 通常表示业务服务没有监听或上游暂时不可达，应先检查服务，不把它当成链接已撤销。

发布状态

queued 或 running 表示需要继续等待。failed 或 canceled 表示发布未完成。成功后仍要核对返回的版本是你本次要发布的版本。

进度百分比不是剩余时间，100%也需要和成功状态一起检查。

常见错误

模型或其他发布检查失败时，阅读返回说明，核对你选择的能力；无法处理就提供错误码给支持人员，不自行更换账号或隐藏问题。

HTTP 状态

• 202：已受理，仍需等待结果。
• 401/403：检查登录或访问权限，不尝试访问他人数据。
• 409/412：内容发生冲突，重新查询再确认。
• 429/5xx：限流或服务暂时异常，按提示有限等待，不无限重试。

只上传完成业务所需的数据，只执行你已经确认的操作。开发工具有访问能力，并不代表它应该自动发布、收费调用或删除内容。

账号与密码

• 不把密码、访问令牌、Cookie 或私钥写进源码和文档。
• 不要求用户复制浏览器登录数据。
• 云端连接只提交 SSH 公钥，不上传私钥。
• 使用系统密码管理器保存工具会话，不使用普通文本文件兜底。
• 不把临时登录链接发给别人。

业务文件

本地修改先用临时副本，检查差异和敏感内容后再上传。只有环境和连接都可用，并且开发者确认本次同步后，才执行文件传输。

对用户文件只读取本次明确提供的内容；不要扫描历史目录、其他用户资料或浏览器数据。

发布会保留哪些开发修改

云端环境允许安装系统包、全局依赖并修改业务文件。平台管理的运行程序会在发布时重新准备，但平台管理目录之外的开发者自有修改可能随正式版本保留。

发布前不要只检查 /oasn。还要检查自己使用过的 /tmp、个人下载目录、shell 历史、npm/pip 缓存、浏览器资料、自建日志、备份、诊断文件和数据库。只清理归属明确的内容，不删除不认识的系统或平台文件。

端口

网页服务端口需唯一，范围为 1..65535。平台保留端口 22、18789、18790 不用于业务网页。

服务监听 0.0.0.0:<已声明端口>，使用平台返回的访问链接，不自行拼外部端口。

文件大小

• 使用说明 Markdown 不超过 1 MiB。
• Agent 介绍图片支持 PNG、JPEG、WebP，不超过 5 MiB。
• 转交其他 Agent 的单次附件最多 100 个，不能重复引用。

具体输入格式以当前工具参数为准。不能把网盘地址、本机路径或编码字符串随意替换为附件对象。

多 Agent 调用

idempotency_key 长度为 16–128，使用字母、数字、下划线和连字符。最多支持 8 层调用，不允许循环调用同一条链中已经使用的版本。

子任务受当前任务剩余时间限制。失败或结果未知时不自动换键重试，以免重复执行或收费。

不要承诺永久有效

开发连接和临时结果链接会过期。需要长期保留的业务结果，及时按允许方式下载；正式结果页能否重开需要单独测试。

这里解释的是你在开发页面和命令中会遇到的概念，不要求你学习平台内部架构。

OpenAgent

你开发并发布的 AI 服务。它接收用户要求，使用程序、模型和工具，返回文字、文件或交互网页。

草稿版本与已发布版本

草稿用于修改和测试，已发布版本用于向用户提供服务。一个 Agent 可以有多个版本，修改前先确认目标。

云端开发环境

平台为你准备的 Linux 开发环境。你可以上传代码、安装依赖并测试。命令中的 workspace 指这个环境，workspace_id 是它的编号。

目标草稿与来源版本

目标草稿是本次准备修改和发布的版本；来源版本只提供创建环境时的初始文件。二者可以不同。创建前通过 workspace sources 查询，由开发者确认具体来源；不要把推荐项或“最新版本”自动当作授权。

默认 Agent：main

每次请求首先进入名为 main 的 Agent。主要业务说明和扩展必须能从这个入口使用。

技能（Skill）

一组可重复执行的任务说明，可以包含脚本和资源。常用于规定“遇到这种需求时怎样完成”。

插件（Plugin）

为 Agent 增加工具或运行功能的软件扩展。安装文件存在不代表已经加载，需要实际测试。

MCP

连接工具和数据服务的一种标准方式。Agent 通过工具列表了解可用功能，并按工具返回的参数说明调用。

对话页面

用于向开发中的 Agent 发送请求并检查回复的网页，也可能显示为 WebChat。

交互网页

Agent 返回给用户操作的业务页面，也称 WebUI，例如报告、图表或编辑界面。它与开发对话页面不是同一个入口。

使用说明：MOM

说明 Agent 适合做什么、需要什么输入、返回什么以及有哪些限制。编写时以用户能发起有效请求为目标。

命令行工具：CLI

在终端执行的工具。本套文档使用 oasn-sa-dev 管理登录、Agent、版本、开发环境和发布。

固定操作键

命令中的 idempotency_key 或 --idempotency-key 用于识别同一次操作，避免网络重试导致重复执行。同一次操作不换键，新的任务才使用新键。

保存标记：etag

草稿查询返回的版本标记。保存时原样带上，防止意外覆盖别人或另一次操作已经保存的内容。

这个教学示例演示最小文本型 OpenAgent。它不是一个已经替你部署好的 Agent，请在自己的开发环境中完成测试。

目标

用户提供一段文档，Agent 返回三条摘要。没有文档时，提示用户补充，而不是自行猜测内容。

放置业务说明

把规则写入 /oasn/AGENTS.md，并确保默认 main Agent 可以使用：

# 文档摘要助手

当用户提供需要总结的文档时：

1. 只使用本次提供的资料。
2. 提取三条关键结论，保持原文含义。
3. 对不清楚或缺少依据的内容明确标注。
4. 没有文档时，请用户先提供内容。

其他 OpenClaw 说明文件按业务实际需要填写，不依赖每次请求都重新初始化环境。

测试

1. 给出一份短文档，检查三条结论是否准确。
2. 给出包含矛盾信息的文档，检查 Agent 是否指出不确定性。
3. 不提供文档，确认它会请求补充。
4. 确认回复没有引用上一次任务的文件或内容。

完成后，再扩展文件结果或交互网页。

假设你已经实现了一个报告网页服务，监听端口 7860，结果页路径为 /results。

1. 配置访问端口

oasn-sa-dev version webui-ports set --version-id <agent_version_id> --ports 7860

等待 sync_status=ready 和 proxy_status=ready，再使用返回的网页链接访问。服务本身应监听 0.0.0.0:7860。

2. 检查网页实现

• 静态资源和 API 使用相对地址。
• 页面中没有密码、访问令牌或写死的内网地址。
• 用户能实际查看、筛选或修改结果。
• 出错时展示可理解的提示。

3. 返回结果

报告已生成，可以在页面中查看和筛选结果。

```oasn-webui
{"type":"webui","title":"分析报告","url":"http://127.0.0.1:7860/results","defaultOpen":true}
```

平台会把符合要求的地址转换为用户可以访问的链接。不要自己猜测外部地址。

4. 发布后再测试

使用正式用户入口发起新任务，检查这次返回的页面。不要复用开发环境的预览链接，也不要仅凭网页返回成功状态就跳过功能测试。

本示例不绑定某个固定供应商。目标是让 Agent 根据当前可用工具查询数据，不把旧工具名或个人密钥写死在程序中。

1. 查看当前工具

先查询开发环境，确认 paid_api_mcp_status=active，并使用本次返回的 paid_api_mcp_url 按外部工具指南保存平台保留连接。然后执行：

sudo -n oasn-paid-mcp probe

检查真实工具名称、必填参数和使用限制。只保留业务需要的工具：

sudo -n oasn-paid-mcp tools --include '<实际工具名>'

认证由受管进程提供，不复制、展示或写入令牌值。选择后再次运行 sudo -n oasn-paid-mcp probe，确认目标工具仍可见。

2. 编写调用规则

当用户请求需要外部数据时：

1. 从当次工具列表选择能够完成任务的工具。
2. 严格按工具说明填写参数。
3. 只解释工具实际返回的数据。
4. 信息不足时说明缺少什么。
5. 失败或结果未知时说明情况，不无限重试或切换个人账号。

3. 测试和费用

用一个正确请求检查结果，再用缺少必填参数或工具不可用的情况检查失败提示。

每次付费调用都可能产生费用，避免把同一查询无条件循环执行。确认费用和结果后，再将能力写入 Agent 介绍。

假设你的 Agent 负责整合报告，另一个 Agent 负责文档分析。先通过当前搜索或选择结果确认目标，不把示例里的名称当成真实编号。

1. 发起专业子任务

当工具列表提供 openagent_agent_run 时，可以发送：

{
  "agent_id": "<本次选中的目标编号>",
  "idempotency_key": "document_analysis_20260831_001",
  "data": {
    "prompt": "请分析本次提供的文档，返回三条关键结论。"
  }
}

有文件时，使用平台提供的附件对象，不直接传自己环境里的路径。

2. 判断是否完成

先看 isError，再看 structuredContent.status。目标成功后，读取 content 中的文字或文件；有网页时读取 structuredContent.views。

目标失败、取消或超时时，向用户说明未完成部分，不自己编造专业结论。

3. 整理给用户

把专业结果转换为当前任务需要的说明、文件或网页。保留目标返回的文件地址，不自己改写；多个网页最多设置一个默认打开。

4. 检查重复与循环

• 同一个子任务重试不换固定键或输入。
• 结果未知时不立即重复调用。
• 任务只拆到必要程度，不循环调用同一组 Agent。
• 确认调用可能产生的费用。
• 最后检查用户实际能阅读、下载或使用结果。