OpenAgent
OpenAgent

实现 Agent

编写 Agent Program

目标结果

把业务规则和必要源码放进 /oasn，让 OpenClaw 的 main Agent 在开发态 WebChat 与正式调用中都能处理同一类任务。

先确认目标运行环境

项目当前开发 Workspace 基线开发含义
业务根目录/oasn业务文件、Skill、Plugin 和可选服务都以这里为根。
Agent RuntimeOpenClaw 2026.6.11配置与扩展必须按该锁定版本验证。
操作系统Debian GNU/Linux 12，amd64本地开发如果不是同一平台，最终仍以远端实测为准。
资源2 vCPU / 4 GiB / 10 GiB rootfs避免依赖超过限制的构建、模型或常驻服务。
预装工具Node.js 22、Python 3.12、Git、OpenSSHCLI 不返回这些工具的精确版本；进入 active Workspace 后按下方命令实测。

取得 status=active 后运行 workspace connect；只有返回 ssh_binding_status=bound 且 ssh_verified=true，才逐字使用该次 connect 返回的 ssh_command 进入当前 Workspace，再执行：

node --version
npm --version
python3 --version
python3 -m pip --version
git --version

把实际输出记入本次开发记录。不要根据本手册、安装日志或另一 Workspace 推断精确补丁版本。

版本工作台的 Program 区域
版本工作台。Program 区域展示 VM、Chat、Models 与 Resources；真正的业务实现位于远端 /oasn。

推荐目录结构

/oasn/
├── AGENTS.md                              # main Agent 的业务规则
├── SOUL.md                                # 可选：表达方式和边界
├── IDENTITY.md                            # 可选：身份说明
├── USER.md                                # 可选：用户上下文约定
├── TOOLS.md                               # 可选：Tool 使用说明
├── skills/<skill-name>/SKILL.md           # 可选：业务 Skill
├── .openclaw/extensions/<plugin-id>/      # 可选：Workspace Plugin
├── service/                               # 可选：业务服务或源码
└── 其他业务源码与静态资源

不要把运行时状态当作 Program。

Session、日志、PID、设备身份、认证数据库、每个 Agent 的 models.json、Secret、缓存和浏览器数据都不能作为版本内容。/opt/oasn/platform 与 /usr/local/bin/openclaw 由平台管理，发布时可能被覆盖。

按这个顺序实现

  1. 先写清单一任务

    在 AGENTS.md 中定义适用输入、必需信息、输出格式、失败语义与安全边界。先让最小文本任务跑通，再添加文件、Tool、Plugin 或服务。

  2. 确保能力属于 main Agent

    正式调用固定进入 main。可以让 main 调用其他 Agent 或 subagent，但不要把完整业务能力只配置给其他 Agent。

  3. 把扩展放在标准位置

    业务 Skill 放到 /oasn/skills/<skill-name>/；Workspace Plugin 放到 /oasn/.openclaw/extensions/<plugin-id>/。没有使用的目录不要为凑结构而创建。

  4. 在目标环境验证依赖

    依赖声明、安装日志或文件存在都不等于可用。实际验证 import/module、系统命令、Plugin runtime，以及需要的服务重载和一次真实业务请求。

  5. 用 WebChat 验证 main

    只使用 CLI 在 status=active 时返回的 WebChat URL，覆盖正常、附件与边界请求。详细门禁见“测试与验收”。

正式输入契约

普通 Skill 或 Plugin 通常直接处理 main 收到的消息与附件路径，不需要自行解析完整 JSON。只有业务确实需要结构化原始输入时，才读取：

/oasn/in/invocation.json
字段含义约束
input.user_prompt本次用户文本内容为空或不足时明确向用户补充，不自行编造。
input.attachments本次附件路径列表只处理列出的路径；不要扫描目录、猜测或复用历史文件。

/oasn/in 是正式调用时的平台输入，不应被 Program 写入或作为持久状态使用。实际 invocation.json 还包含平台和运行时字段，可能带短期敏感材料；禁止把整份文件输出到日志、最终回复或截图。开发态 WebChat 不保证生成同一份正式调用 JSON，因此不要把“WebChat 中看到了某个本地文件”误写成正式输入契约已经通过。可直接跟做的脱敏 JSON 示例、解析代码与正式验收方法见 结构化输入与 WebUI JSON。

输出契约

  • 文本：main 必须返回非空最终回复。
  • 文件：生成真实文件并在最终回复中作为附件或可下载 Markdown 链接返回；只回复 /oasn/... 路径不合格。
  • WebUI：先用 CLI 0.7.3 为版本声明端口，让服务监听 0.0.0.0:<声明端口>，再在最终回复中返回严格的 oasn-webui JSON block；完整字段、URL 与失败语义见 结构化输入与 WebUI JSON。
  • 敏感信息：不得输出 .env、密钥、Cookie、会话、日志、缓存或浏览器数据。

完成定义

以下条件同时成立，才能把 Program 标为已完成：

  • 所有业务文件都在 /oasn，且没有依赖本地未上传文件。
  • main 能完成代表性任务，并对缺失输入返回清晰、可行动的提示。
  • 使用的每个依赖、Tool、Plugin 或 MCP 均在远端运行表面真实验证。
  • 附件只来自本次显式输入；产物可被用户真实打开或下载。
  • 没有 Secret、临时状态或平台管理文件进入版本内容。

搜索文档

推荐搜索