# Install OpenAgent: OpenClaw Give this guide to OpenClaw Desktop and ask it to install OpenAgent. The current Desktop task downloads and installs the plugin, completes OAuth, then creates an onboarding conversation and sends the fixed prompt in the same turn. Navigate automatically only when this turn's navigation capability has been confirmed. The user only completes authorization in the page that opens. Execute these steps when asked to install and finish step 4 before ending the current turn. Report concrete blockers; do not merely provide instructions or end by saying installation is about to start. ## User-visible output Start with only “Installing OpenAgent…”. Only after the installer confirms that the authorization page has opened and user authorization is still needed, say “Please sign in to OpenAgent on the page that opened…” once. Do not request sign-in when valid authorization is reused. Only after this installer confirms OAuth has been verified, you may say “Authorization is complete. Opening the new-user guide…” once, whether authorization was newly completed or reused. Do not wait for the model in the new conversation to finish. Do not repeat reminders or narrate each step while waiting on the same process. The final reply must contain exactly the two lines in “Completion report”, without blank lines, headings, lists, code fences, or additions. Installer logs and tool receipts are for internal verification; do not repeat installation paths, permission settings, tool inventories, session or run identifiers, receipt paths, raw state fields, OAuth details, or account information. Tool calls and logs displayed by the Host itself are outside this reply constraint. The new onboarding conversation uses its own Skill's stage update and fixed body. ## 1. Check the environment and download the plugin Require OpenClaw `2026.10.7` or later, Python 3, Git, a running local Gateway, and a configured model. The current Desktop task must have local `exec`, `process`, and native `sessions_send`; automatic navigation additionally requires `screen` and a requesting window target for this turn. Confirm that CLI and Desktop use the same OpenClaw installation. Do not install in a remote sandbox, change models, or bypass Host permission checks. Retain the current installation task's actual `sessionKey` from trusted session context; if absent, call native `session_status` once. Never infer it from a title, history, or another task. When `screen` is available, call it once with `{"action":"focus","sessionKey":""}` and record this turn's navigation capability. Only `ok=true` permits one `navigate` call in step 4. When several people participate, use the current requester's verified `requester_profile.id` according to the tool schema, never an Agent ID or session ID. If `screen` is absent, no requesting window was captured (such as `no requesting Control UI`), the window disconnects, or the result is unconfirmed, record automatic navigation as unavailable and continue normal installation, creation, and sending. An explicit permission or approval denial stops the flow; do not switch channels. Never use standalone RPC or another window to perform navigation. The state directory is `OPENCLAW_STATE_DIR`, or `~/.openclaw` when unset. For another local directory, use the same `--openclaw-home ` for installation, receipt recording, and removal. If `OPENCLAW_CONFIG_PATH` is set, it must point to `openclaw.json` in that directory. At the start of this explicit installation request, the Host generates one canonical lowercase UUID with local `python3 -c 'import uuid; print(uuid.uuid4())'` and retains it as this request's `installation_id` in the original turn. Pass the same `--installation-id` to installation, preparation, and recording. A new explicit installation request uses a new ID and a new onboarding conversation, even for the same plugin version. Do not change the ID to retry a short wait, cancellation, failure, or unknown result within this request. Create an empty directory with `mktemp -d /tmp/openagent-openclaw.XXXXXX`, retain its actual path, then download the official `rel` branch: ```bash git clone --depth 1 --branch rel https://gitee.com/openagent-org/openclaw-plugin.git ``` Only DNS, connection, timeout, interrupted transfer, or HTTP 5xx download failures permit one attempt from `https://github.com/openagent-org/openclaw-plugin.git` in another new directory. Permission or approval denial, certificate errors, 401/403/404/429/451, installation failures, and OAuth failures do not permit source switching or installation replay. After cloning, read `INSTALL.en.md` from the actual download directory and continue from step 2 using that bundled guide, the same directory, and the same `installation_id`. Do not download again or reuse MCP Apps preflight steps from an earlier conversation or cached guide; installation no longer requires enabling `mcp.apps.enabled` or restarting the Gateway for Apps. If an obsolete invocation reports that the preflight was removed, it only skipped that step and did not complete installation. ## 2. Run installation once and complete OAuth Send the starting message from “User-visible output”, then immediately run this once through local `exec` in the same turn. Do not repeat a starting message already sent. Substitute the actual path and quote it correctly if it contains spaces: ```json {"title":"Install OpenAgent and wait for authorization","command":"python3 /install.py --installation-id ","yieldMs":60000,"timeoutSeconds":1200} ``` If `exec` returns a still-running process and a `sessionId`, keep waiting on that same process through `process`: ```json {"action":"poll","sessionId":"","timeout":30000} ``` The installer uses native OpenClaw CLI commands to install and enable the plugin, configure MCP, and check OAuth. It reuses valid authorization; otherwise it opens the authorization page once, waits for the user, then requires the native login process to exit successfully and the authorization-status readback to pass. Full installation retains file, ownership, MCP configuration, and browser-permission checks, then reserves onboarding immediately after OAuth passes. It does not run a separate CLI tool probe first; the new onboarding conversation performs actual tool verification in step 4. Do not start another login, copy authorization URLs, or request passwords or tokens. A short wait ending is not failure. Cancellation, failure, timeout, or an unknown result preserves the state and stops automatic replay. A full installation also enables OpenClaw's bundled `browser` through native plugin management so discovery and result pages can open automatically. Explicit disable settings stop installation without being changed: `plugins.enabled=false`, `browser` in `plugins.deny`, `plugins.entries.browser.enabled=false`, or `browser.enabled=false`. The installer then reads the live Gateway registry through `plugins.list`. An enabled bundled `browser` with `runtime.state=active` is reused without enabling or reloading it again. Only a confirmed inactive plugin without a load error is enabled and added to an existing nonempty allowlist; other plugins are preserved. Missing fields, inconsistent states, or a failed query stop installation and must not be treated as permission to enable again. Native enablement must confirm hot loading. A failure, unknown outcome, or restart requirement stops before OAuth without an automatic retry or restart. The installation turn may retain the browser instance, so do not run `plugins reload browser --wait` inside that same turn to wait for itself to end. Preserve and report the failed request. `--skip-connect` retains offline installation/configuration behavior, and `--login-only` restores authentication and still runs CLI tool discovery; neither enables the browser or changes tool permissions. This bundled browser and its permissions are shared Host functionality and remain when OpenAgent is removed. A loaded plugin does not establish that the current tool policy permits `browser`. A full installation preserves `tools.profile` and appends only the exact `browser` entry to the existing `tools.alsoAllow` when `coding`, `minimal`, or `messaging` lacks browser access. It makes no change for `full`, an unset profile, or an existing `alsoAllow` entry that already covers the browser. It does not switch to `full` or remove deny rules. Stop automatic handling and report the policy blocker when an explicit `deny` matches the browser, `allow` excludes it, `allow` conflicts with the required `alsoAllow`, or an Agent/provider has an independent tool policy that affects inheritance. Write through native `config set tools.alsoAllow --strict-json`, requiring the previous value or requiring the authored field to be absent; then read back the result and check policy again. Concurrent changes, failure, or an unknown result stop without an automatic retry, reload, or restart. Configuration readback does not replace checking tool availability in the current Desktop conversation. ## 3. Create an empty onboarding conversation in the original turn OpenClaw `2026.10.7` supports hot loading for this Skills bundle and default MCP configuration, normally without a restart. Only if the Host explicitly requires one, tell the user, restart the same Gateway as directed, and wait for recovery; do not reinstall or log in again because of it. Installation and OAuth do not update the current installation turn's effective tool allowlist. Create an ordinary empty conversation immediately so its first run loads and verifies the latest tools. Do not use `sessions_spawn`, which inherits the old allowlist, or queue a self-followup. Determine whether the original turn has a usable window target from step 1's result. This request's receipt retains strict `format=2` validation at `/openagent-onboarding//.json`. Accept only a receipt whose `installation_id` matches this request. Never reuse or navigate to a previous installation's conversation, or use a legacy version-level `.json` receipt as this request's destination. Preserve existing conversations and receipts; a new installation does not require uninstalling or clearing them. If the installer returns this request's `OPENAGENT_ONBOARDING` with `submission=accepted`, reuse only this request's accepted destination to prevent duplicates, then follow step 4's navigation and reporting instructions without creating or sending again. Only for this request's `OPENAGENT_ONBOARDING_REQUEST` with `submission=reserved`, retain the complete request output, the same `installation_id`, `request_id`, installed directory, and state directory, then run this once in the original turn: ```bash python3 -B '/desktop_onboarding.py' --prepare --installation-id '' --request-id '' --source-session-key '' ``` Use the installed directory reported by the installer, normally `~/.openclaw/extensions/openagent`; append the same `--openclaw-home ` for a custom state directory. The helper verifies the source conversation, persists the destination identity, and uses official CLI to create an empty conversation once. It sends no message, preserves `OPENCLAW_SHELL`, and neither changes permissions nor fabricates a parent-child relationship. Retain the complete returned request. Failure, timeout, unknown outcomes, or repeated preparation stops without another creation or another channel. ## 4. Send the fixed prompt and handle navigation Call native `sessions_send` **once** using the complete `arguments` from this successful preparation, retaining `timeoutSeconds=0` and the prepared destination. Do not send to the installation conversation itself or use shell to send a message. Keep `message` exactly as follows: ```text OpenAgent 已安装,打开新用户引导 ``` The new conversation is independently visible and accepts further input without copying installation history. Preserve native `sessions_send` inter-session provenance; do not impersonate a direct human message or remove its provenance envelope. Do not rename, archive, or clean up old conversations, or resend the prompt. An ordinary conversation may return its completion to the installation task; that return is only a result, never a trigger to install, send, or create again. After the native result returns `status=accepted`, the same prepared `sessionKey`, and an actual `runId`, record it with this reservation's `request_id`: ```bash python3 -B '/desktop_onboarding.py' --record --installation-id '' --request-id '' --session-key '' --run-id '' ``` In the recorded result, `submission=accepted` means the new task was accepted; `input_state=consumed` means the prompt entered the conversation. Use these fields only for internal decisions. Do not treat an unconfirmed state as success, recreate, or resend. Only if step 1's `focus` returned `ok=true`, immediately call `screen` once in the original installation turn with `{"action":"navigate","sessionKey":""}`, using the same verified requester. `ok=true` confirms only that navigation was sent to that window, not that onboarding has answered. A pending readback must not prevent navigation to an accepted conversation; a conflicting receipt, cancelled input, or mismatched destination stops the flow. If navigation was skipped, the window disconnects, or navigation is unconfirmed, preserve the created conversation, explicitly report that automatic navigation was not completed, and provide the session link actually returned by the Host. If none was returned, tell the user to open it from the conversation list without guessing a URL, navigating repeatedly, or creating a replacement. An explicit permission or approval denial stops further actions; do not switch channels. The parent installation turn internally checks the actual plugin-file, OAuth, task-acceptance, and automatic-navigation states, then replies only as specified in “Completion report”. Neither `accepted`, `consumed`, nor successful navigation proves model execution, guide verification, or account verification. `OPENAGENT_ONBOARDING_REQUEST`, `OPENAGENT_ONBOARDING`, and preparation/recording receipts are tool states, not user-visible prose. The parent does not repeat the onboarding conversation's fixed body or make extra account or business-tool calls; installation ends here. Preserve failed or unknown states without automatically logging in again or changing the installation ID. Following the guide Skill, the new onboarding conversation first sends one standalone `OpenAgent: Installation Check — ` stage update, then confirms that all five OpenAgent Skills are available in this conversation and the guide Skill has loaded. Only after one guide call succeeds with `view=onboarding` and `status=ready`, followed by one successful account call with strictly `success=true`, may its final reply contain only the localized fixed Markdown body and end the turn. An unavailable animation card does not mean the guide call failed and does not prove playback. If tools are missing, either call fails, or results are incomplete or unknown, report “OpenAgent installation verification is incomplete”, the failed stage, and a public error code or brief sanitized reason. Do not emit the fixed success body, resend, or automatically retry. The new onboarding conversation must discover all five Skills in its current catalog and load the guide Skill through OpenClaw's native mechanism: - `openagent-first-task-router` - `openagent-guide-agent` - `openagent-search-agent` - `openagent-run-agent` - `openagent-query-account` ## Completion report Use the following two lines only after this installer exits successfully, file, ownership, MCP configuration, browser-permission, and OAuth checks have passed, native submission to this onboarding conversation has been accepted, the recording command has exited successfully, and its complete receipt confirms this request's acceptance and matching destination without conflict or cancellation. Replace `{version}` with the version from this installation's verified installed `plugin.json`; use the incomplete template if the version cannot be confirmed. A pending input readback in the new conversation does not block reporting installation setup as complete. Do not wait for the model to finish or claim that guide or account verification has completed. ```text OpenAgent {version} installation setup is complete. The new-user guide has been submitted; if you are not redirected, open it from the conversation list. ``` If navigation was skipped, the window disconnected, or navigation is unconfirmed, keep the first line and replace the second with “Automatic navigation did not complete. Open the new-user guide from the conversation list.” If the Host actually returned a conversation link, use “Automatic navigation did not complete. [Open the new-user guide](actual-conversation-link).” with that real link instead; this is the only permitted link. Never guess a link or ask the user to reinstall, sign in again, create another conversation, or resend the prompt. If installation, authorization, conversation creation, or submission fails, the user cancels, permission or approval is denied, an operation times out, or a required result is unknown, output only these two lines. Fill in the actual stage's brief sanitized reason and the next available action, without a technical checklist or an automatic retry. An explicit permission or approval denial takes precedence and uses this incomplete template, even during navigation. Use the previous paragraph's navigation template only for missing navigation capability, disconnection, or an otherwise unconfirmed navigation result. ```text OpenAgent installation is incomplete: {brief reason}. Next step: {currently available action}. ``` ## Uninstall Use the [one-line command in the README](./README.md#uninstall). First end tasks using OpenAgent and run it outside the plugin directory. The uninstaller checks file and configuration ownership, removes only this plugin and its MCP/OAuth connection, and preserves other plugins, models, and conversations, including shared `browser` enablement and tool permissions. Local removal does not revoke server-side authorization. Preserve existing onboarding conversations and receipts. Legacy version-level receipts remain subject to the uninstaller's existing verification and archival rules; preserve any unconfirmed, failed, or currently written receipt. A new explicit installation request creates its onboarding conversation with a new `installation_id`, without requiring prior uninstallation or receipt removal. Inspect legacy channel versions, different versions, local changes, or unknown same-name installations first; do not overwrite them or delete shared directories. If removal encounters the Host's configuration-shrink protection, follow the error instructions to stop the target Gateway before proceeding. Do not delete configuration or automatically replay removal.