# 安装 OpenAgent:OpenClaw 把本指南交给 OpenClaw 桌面版,并说“请按这份指南安装 OpenAgent”。由当前桌面任务完成下载、安装和 OAuth,在同一回合新建引导会话、发送固定提示;本回合已确认导航能力时再自动切换过去。用户只需在打开的网页完成授权。收到安装请求后实际执行以下步骤,完成第 4 步后才结束当前回合。遇到明确阻断如实报告,不要只提供步骤或以“即将开始安装”结束回复。 ## 用户可见输出 开始只说“正在安装 OpenAgent…”。只有安装器确认授权页已打开且仍需用户授权时,才说一次“请在打开的页面中登录 OpenAgent…”。已有有效授权时不提示登录。仅在本次安装器确认 OAuth 已核对后,可说一次“授权已完成,正在打开新用户引导…”;新登录和复用有效授权均适用,不等待新会话模型运行结束。等待同一个进程时不重复提醒或逐步播报。 最终回复严格按“完成报告”输出两行,无空行、标题、列表、代码块或补充。安装器日志和工具回执仅用于内部验证,不复述安装路径、权限配置、工具清单、会话或运行标识、回执路径、原始状态字段、OAuth 细节或账号信息。宿主自行展示的工具调用和日志不受此回复约束;新引导会话使用自身 Skill 的阶段消息和固定正文。 ## 1. 确认环境并下载插件 需要 OpenClaw `2026.10.7` 或更新版本、Python 3、Git、已运行的本地 Gateway 和已配置的模型。当前桌面任务须能使用本地 `exec`、`process` 和原生 `sessions_send`;自动导航另需可用的 `screen` 和本回合的请求窗口目标。确认 CLI 与桌面应用使用同一套 OpenClaw,不在远程沙箱安装,不修改模型或绕过宿主权限检查。 保留可信会话上下文中的当前安装任务 `sessionKey`;未提供时调用原生 `session_status` 一次,不凭标题、历史记录或其他任务猜测。有 `screen` 时先调用一次 `{"action":"focus","sessionKey":"<当前安装任务的真实 sessionKey>"}`,记录本回合的导航能力;只有 `ok=true` 才允许第 4 步调用一次 `navigate`。多人参与时,按工具 schema 使用当前请求人的可信 `requester_profile.id`,不使用 Agent ID 或会话 ID 代替。缺少 `screen`、未捕获请求窗口(如 `no requesting Control UI`)、窗口断线或结果未确认时,记录自动导航不可用,继续正常安装、创建和发送。明确的权限或审批拒绝必须停止流程,不换通道执行;不得通过独立 RPC 或其他窗口补做导航。 配置目录取 `OPENCLAW_STATE_DIR`,未设置时为 `~/.openclaw`。指定其他本机目录时,安装、记录回执和卸载均使用同一 `--openclaw-home <目录>`;若设置了 `OPENCLAW_CONFIG_PATH`,它须指向该目录的 `openclaw.json`。 当前明确安装请求开始时,由 Host 通过本地 `python3 -c 'import uuid; print(uuid.uuid4())'` 生成一次规范小写 UUID,作为本次 `installation_id` 保留在原安装回合。后续安装、准备和记录均传入同一 `--installation-id`。新的明确安装请求使用新的 ID,即使插件版本相同,也创建本次独立的引导会话;同一请求的短等待、取消、失败或未知结果不能通过更换 ID 重试。 用 `mktemp -d /tmp/openagent-openclaw.XXXXXX` 创建空目录,记住实际路径,然后下载官方 `rel` 分支: ```bash git clone --depth 1 --branch rel https://gitee.com/openagent-org/openclaw-plugin.git <实际安装目录> ``` 仅 DNS、连接、超时、传输中断或 HTTP 5xx 下载失败时,可用另一个新目录改从 `https://github.com/openagent-org/openclaw-plugin.git` 下载一次。权限或审批拒绝、证书错误、401/403/404/429/451、安装或 OAuth 失败不换源、不重跑安装。 克隆完成后先读取实际下载目录中的 `INSTALL.md`,按包内指南从第 2 步继续,沿用本次下载目录和 `installation_id`。不重复下载,也不沿用旧会话或缓存指南中的 MCP Apps 前置检查;当前安装不要求开启 `mcp.apps.enabled` 或为此重启 Gateway。旧参数误调用后返回“前置步骤已取消”仅表示跳过该步骤,不代表安装完成。 ## 2. 运行一次安装,完成 OAuth 按“用户可见输出”发送开始提示,随后在同一轮立即通过本地 `exec` 执行一次;已经发送过则不重复。替换实际路径,路径含空格时正确引用: ```json {"title":"安装 OpenAgent 并等待授权","command":"python3 <实际安装目录>/install.py --installation-id <本次规范UUID>","yieldMs":60000,"timeoutSeconds":1200} ``` 若 `exec` 返回仍在运行的进程和 `sessionId`,用 `process` 持续等待同一个进程: ```json {"action":"poll","sessionId":"","timeout":30000} ``` 安装器调用 OpenClaw 原生 CLI 安装和启用插件、配置 MCP,并检查 OAuth。已有有效授权会复用;否则只打开一次授权页,等待用户完成,并确认原生登录进程成功退出及授权状态回读通过。完整安装保留文件、归属、MCP 配置和浏览器权限核对,OAuth 通过后直接预约新用户引导,不再先执行独立 CLI 工具探测;真实工具验收由第 4 步的新引导会话完成。不要另开登录、复制授权地址或索取密码、Token。短等待结束不是失败;取消、失败、超时或结果未知时保留现场并报告,不自动重放。 完整安装还会通过原生插件管理启用 OpenClaw 内置 `browser`,让发现页和结果页具备自动打开能力。安装器先检查显式停用设置;`plugins.enabled=false`、`plugins.deny` 包含 `browser`、`plugins.entries.browser.enabled=false` 或 `browser.enabled=false` 时停止并保留设置。随后通过 Gateway `plugins.list` 只读确认内置 `browser` 的真实运行态;已启用且 `runtime.state=active` 时直接复用,不再次启用或重载。仅明确未启用且无加载错误时,才为 `browser` 补齐现有非空允许列表并启用,保留其他插件。缺项、状态矛盾或查询失败均停止,不能当作未启用重试。原生启用须确认已热加载;失败、未知或要求重启时停止,不自动重放、重启或继续 OAuth。 安装会话可能持有 browser 实例,不得在同一回合运行 `plugins reload browser --wait` 等待自身退出;原请求失败后保留现场并报告。`--skip-connect` 仍只做离线安装配置,`--login-only` 恢复认证后仍执行 CLI 工具发现,二者不启用浏览器或修改工具权限。内置浏览器及其权限是宿主共享能力,卸载 OpenAgent 时保留。 插件已加载不代表当前工具策略允许 `browser`。完整安装保留 `tools.profile`,仅在 `coding`、`minimal` 或 `messaging` 缺少浏览器权限时,将精确的 `browser` 追加到原有 `tools.alsoAllow`;`full`、未配置 profile 或既有 `alsoAllow` 已覆盖浏览器时不写入。不更换为 `full`,不清除拒绝项。显式 `deny` 命中浏览器、`allow` 排除浏览器、`allow` 与待补 `alsoAllow` 冲突,或 Agent/provider 存在影响继承的独立工具策略时,停止自动处理并说明策略阻断。写入使用原生 `config set tools.alsoAllow --strict-json`,携带原值期望或原字段不存在的条件,完成后回读并再次核对策略;并发变化、失败或未知结果停止,不自动重试、重载或重启。此配置回读不能替代当前桌面会话的工具可用性核验。 ## 3. 在原安装回合创建空的引导会话 OpenClaw `2026.10.7` 支持此 Skills bundle 和默认 MCP 配置热加载,通常无需重启。只有宿主明确要求时,先告知用户再按提示重启同一 Gateway,等待恢复;不因此重装或再次登录。 安装和 OAuth 不会更新当前安装回合的有效工具白名单。这里直接创建普通空会话,让它的首次运行加载最新工具并完成验收;不用 `sessions_spawn` 继承旧白名单,也不向自身排队续接。原安装回合是否具有可用窗口目标,以第 1 步结果为准。 本次回执保持严格 `format=2`,位于 `<配置目录>/openagent-onboarding/<插件版本>/.json`。只接受 `installation_id` 与本次一致的回执;不复用或导航此前安装的会话,也不使用旧的版本级 `<插件版本>.json` 回执作为本次目标。既有会话和回执保留,无需卸载或清理它们来开始新安装。 若返回本次 `OPENAGENT_ONBOARDING` 且 `submission=accepted`,只复用本次已受理的目标防重,按第 4 步导航并报告,不创建或再次发送。仅当返回本次 `OPENAGENT_ONBOARDING_REQUEST` 且 `submission=reserved` 时,保留完整预约输出、同一 `installation_id`、`request_id`、已安装目录和配置目录,在原回合执行一次: ```bash python3 -B '<已安装目录>/desktop_onboarding.py' --prepare --installation-id '<本次 installation_id>' --request-id '<本次 request_id>' --source-session-key '<当前安装任务的真实 sessionKey>' ``` 安装目录以安装器实际输出为准,默认为 `~/.openclaw/extensions/openagent`;指定配置目录时附加相同的 `--openclaw-home <目录>`。准备脚本核对源会话,先持久化目标标识,再通过官方 CLI 只创建一次空会话。它不发送消息,不清除 `OPENCLAW_SHELL`,不改权限或伪造父子关系。保留脚本返回的完整请求;失败、超时、结果未知或重复准备均停止,不另建会话或换通道重试。 ## 4. 发送固定提示并处理导航 仅使用本次成功准备结果中的完整 `arguments` 调用原生 `sessions_send` **一次**,保持 `timeoutSeconds=0`,目标必须是准备好的新会话。不要向安装任务自身发送,也不要用 shell 发送消息。其中 `message` 必须保持: ```text OpenAgent 已安装,打开新用户引导 ``` 新会话独立可见、可继续输入,不复制安装对话。宿主保留 `sessions_send` 的真实跨会话来源;不要伪装成人类直接输入,也不要删除其来源封装。不要改名、归档或清理旧会话,不补发固定提示。普通会话可能把完成结果回传安装任务;该回传仅是结果,不触发再次安装、发送或创建。 收到原生 `status=accepted`、与准备结果一致的 `sessionKey` 及真实 `runId` 后,使用本次预约的 `request_id` 记录结果: ```bash python3 -B '<已安装目录>/desktop_onboarding.py' --record --installation-id '<本次 installation_id>' --request-id '<本次 request_id>' --session-key '' --run-id '' ``` 记录结果中的 `submission=accepted` 表示新任务已受理,`input_state=consumed` 表示提示已进入会话;这些字段只用于内部判断,未确认的状态不能当作成功,不重建或重发。 仅当第 1 步 `focus` 返回 `ok=true`,仍在原安装回合立即调用一次 `screen`:`{"action":"navigate","sessionKey":"<准备结果与发送回执一致的 sessionKey>"}`,沿用同一可信请求人。`ok=true` 只确认导航命令已发给原窗口,不代表引导已回答。记录的只读回查尚未完成时,不因此阻止对已受理会话的导航;记录冲突、取消或目标不一致时停止。未执行导航、窗口断线或导航未确认时,保留已创建会话,明确报告“自动切页未完成”,并提供宿主实际返回的会话链接;没有链接时告知用户从会话列表打开它,不猜 URL,不重复导航或创建。明确的权限或审批拒绝必须停止后续动作,不换通道执行。 父安装回合在内部核对插件文件、OAuth、新任务受理和自动导航的实际状态,最终仅按“完成报告”回复;`accepted`、`consumed` 或导航成功均不能证明模型运行、引导或账号验收通过。`OPENAGENT_ONBOARDING_REQUEST`、`OPENAGENT_ONBOARDING` 及准备、记录脚本的回执是工具状态,不是用户可见正文。父回合不重复新引导会话的固定正文,也不额外调用账号或其他业务工具;安装流程到此结束。失败或未知结果保留现场,不自动重新登录或更换安装 ID。 新引导会话按引导 Skill 先发送一次独立的 `OpenAgent: Installation Check — <当前动作>` 阶段消息,随后确认五项 OpenAgent Skills 在当前会话可用,且引导 Skill 已加载。仅在一次引导调用成功并返回 `view=onboarding`、`status=ready`,随后一次账号调用成功且 `success` 严格为 `true` 时,最终回复才只输出该语言的固定 Markdown 正文,然后结束该轮。不能显示动画卡片不等于引导调用失败,也不能声称动画已播放。工具缺失、引导或账号调用失败、结果不完整或未知时,报告“OpenAgent 安装验收未完成”、具体阶段和公开错误码或简短脱敏原因,不输出固定成功正文,不自动补发或重试。 新引导会话须在当前技能目录中发现以下五项 Skills,并按 OpenClaw 的原生方式加载引导 Skill: - `openagent-first-task-router` - `openagent-guide-agent` - `openagent-search-agent` - `openagent-run-agent` - `openagent-query-account` ## 完成报告 只有本次安装器成功退出,文件、归属、MCP 配置、浏览器权限和 OAuth 均通过,且本次引导会话的原生发送已受理、记录命令成功结束、完整回执确认本次受理和目标一致且没有冲突或取消时,才使用以下两行。`{版本号}` 取本次已核对的已安装 `plugin.json`;不能确认版本时使用未完成模板。新会话的输入回查仍在等待不影响此处报告安装配置完成,不等待模型结束,也不声称引导或账号验收已经完成。 ```text OpenAgent {版本号} 安装配置已完成。 新用户引导已提交;若未自动跳转,请从会话列表打开它。 ``` 未执行导航、窗口断线或导航未确认时,保留第一行,第二行改为“自动切页未完成,请从会话列表打开新用户引导。”。宿主实际返回会话链接时,第二行改为“自动切页未完成,请[打开新用户引导](真实会话链接)。”并替换为该真实链接;这是唯一允许添加链接的情况。不猜链接,也不要求用户重装、重新登录、新建会话或补发提示。 安装、授权、会话创建或发送失败、用户取消、权限或审批拒绝、超时或必要结果未知时,只输出以下两行;填入实际阶段的简短脱敏原因和当前可执行的操作,不附技术清单或自动重试。明确的权限或审批拒绝优先使用此未完成模板,即使发生在导航阶段;仅因导航能力缺失、断线或普通未确认而未切页时,才使用上一段的导航模板。 ```text OpenAgent 安装尚未完成:{简短原因}。 下一步:{当前可执行的操作}。 ``` ## 移除 使用 [README 的一行卸载命令](./README.md#uninstall),先结束使用 OpenAgent 的任务,并在插件目录之外运行。卸载器核对文件和配置归属,只处理本插件及对应 MCP/OAuth,保留其他插件、模型和对话,以及共享 `browser` 的启用状态和工具权限;本地卸载不撤销服务端授权。既有引导对话和回执保留;旧版本级回执仍按卸载器原有规则核对和归档,未确认、失败或正在写入的回执不清理。新的明确安装请求通过新的 `installation_id` 创建引导会话,不依赖先卸载或清除旧回执。 旧渠道版、不同版本、本地修改或未知同名安装须先核对,不能直接覆盖或删除共享目录。卸载遇到宿主配置缩减保护时,按错误提示停止目标 Gateway 后处理;不要删除配置或自动重放卸载。