> ## Agent Instructions > Treat Clawdi as one product. > Recommend the Cloud Agent quickstart for most new users. > Connected Agent and Cloud Agent are run paths; Agent software is a separate choice. > Do not present shared Clawdi capabilities as exclusive to one run path. # Authentication Source: https://docs.clawdi.ai/account/authentication Sign in to Clawdi from the dashboard or CLI and manage the login stored on your computer. Your Clawdi account is shared across the dashboard, Connected Agents, and Cloud Agents. Signing in does not change where an Agent runs or which Agent software it uses. ## Sign in from the dashboard Open the [Clawdi dashboard](https://cloud.clawdi.ai) and complete the browser sign-in flow. Use the same account when the CLI opens a browser for authorization. ## Sign in from the CLI ```bash theme={null} clawdi auth login ``` The CLI uses the OAuth device authorization grant. It prints a sign-in link and a short code, and opens a browser in a local interactive terminal. Open the link, sign in, check that the page shows the same code, and approve. The CLI finishes automatically and stores the login under `~/.clawdi/auth.json` by default. Treat that file as a credential: do not copy it into a repository, support ticket, or chat. For clawdi.ai, the verification page is [accounts.clawdi.ai/device](https://accounts.clawdi.ai/device). The code expires after 10 minutes. Approve only a sign-in you started yourself. Check the active credential source without printing the token: ```bash theme={null} clawdi auth status ``` The output can still contain your email address, user ID, local paths, and API origin. Redact those fields before posting it publicly. ## CLI permissions Starting in CLI **0.15.7**, signing in with `clawdi auth login` gives the CLI the same access as the dashboard, with these exceptions: * **Cloud:** review or revoke API keys and approve device sign-ins in the browser. * **Hosted billing:** enter payment methods, enable automatic Wallet reload, and change plans in the browser. `clawdi wallet portal` prints the billing URL. New API keys can no longer be created. The dashboard lists existing keys with their permissions and expiry so you can revoke them. Existing API keys retain their limited permissions. Signing in with an API key through `--manual` does not grant the access provided by browser sign-in. CLI versions before **0.15.0** can no longer complete sign-in. [Update the CLI](/installation/update) before running `clawdi auth login`. ## Sign in over SSH or without a browser ```bash theme={null} clawdi auth login ``` Open the printed link on any device with a browser, confirm the code matches the terminal, and approve. Keep the command running; it finishes automatically after approval. Use `--no-open` to skip opening a browser automatically. If the command was interrupted, resume waiting for the same sign-in: ```bash theme={null} clawdi auth complete ``` If the code expired or you denied the request, run `clawdi auth login` again for a new code. ## Self-hosted For [self-hosted Clawdi](/self-hosting) using Clerk OAuth, follow [Clerk's OAuth application settings guide](https://clerk.com/docs/guides/configure/auth-strategies/oauth/device-authorization-grant#configure-an-oauth-application): in the Clerk Dashboard, open **OAuth applications**, select the CLI's OAuth application, and enable **Device authorization grant**. Through the [Clerk Backend API](https://clerk.com/docs/reference/backend-api/tag/OAuth-Applications#operation/UpdateOAuthApplication), set `device_authorization_grant_enabled` to `true` on that application. If the grant is disabled, the CLI reports that the server's sign-in app does not allow device sign-in and asks an administrator to enable it. As a fallback, sign in with an existing API key in an interactive terminal: ```bash theme={null} clawdi auth login --manual ``` This accepts an existing key; it does not create a new one. ## Switch accounts ```bash theme={null} clawdi daemon uninstall clawdi auth logout clawdi auth login clawdi setup ``` Stop the daemon first so it does not continue using the previous login. After signing in again, run setup to refresh the Connected Agent registration and background service. ## Sign out ```bash theme={null} clawdi auth logout ``` Sign-out removes persisted credentials and cached environments on this computer and attempts to revoke the remote OAuth grant. It does not delete the account or its server-side data. See [Uninstall the Clawdi CLI](/installation/uninstall) when removing the complete local integration. # Notifications Source: https://docs.clawdi.ai/account/notifications Review account updates and Project invitations, then resolve the items that need attention. Use the bell in the [Clawdi dashboard](https://cloud.clawdi.ai) to review account activity and Project invitations. Updates can include Wallet balance alerts, automatic top-up problems, and Agent or account status changes. ## Review updates 1. Open the bell in the top-right corner. Opening the panel marks your account updates read; updates that were unread stay highlighted as new while the panel is open. 2. Choose **Load earlier** when more history is available. 3. Read an update and follow its action. Dashboard links open in the dashboard. 4. Check the current Wallet, subscription, or Agent state and resolve the issue there. You have reviewed the update and checked the current state on its linked page. Read status only shows that you opened the panel, not that the issue is resolved. Notification Center with an Agent activity reminder. Notification Center with an Agent activity reminder. *The demo account has an Agent activity reminder whose action opens the dashboard. The screenshot shows an earlier layout.* [Light full-size image](/assets/clawdi-demo-screenshots/light/notifications.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/notifications.webp) Use an item's menu to remove it. Removing a notification manages your inbox; Wallet, subscription, and Agent changes happen on their own pages. ## Respond to invitations 1. Open the bell and find the Project invitation. 2. Review the Project and sender, then accept or decline. 3. After accepting, open the Project and review its Skills and attached Vaults. 4. To let an Agent use it, open that Agent's **Projects** section and choose **Link** for the accepted Project. Viewer access includes the ability to use attached Vault values through authorized runtime tools. Review that access before linking a shared Project. Accepting grants Project membership. The Agent gains access when you explicitly link the accepted Project. For the full invitation workflow, follow [Share a Project](/guides/workflows/share-a-project). For a payment or trial issue, use [Cloud Agent usage and billing](/cloud-agents/usage-and-billing). Contact [support](/support) when the account or Agent page offers no recovery action. # Permissions and sharing Source: https://docs.clawdi.ai/account/permissions-and-sharing Review Viewer access, share Projects safely, and revoke the right scope of access. A Custom Project owner can grant **Viewer** access through an invitation or share link. Project membership determines who can use its resources; Agent linking determines which Agent can use an accepted Project. ## Understand viewer access * Viewers can read Project Skills and see attached Vault key names. * Authorized CLI and Agent runtime paths can resolve the Project's available Vault values. The dashboard keeps plaintext values hidden. * The owner manages the Project's content, Skills, and Vault data. * Global and Agent Projects are personal working spaces; use a Custom Project for sharing. Share a Project only with someone who should be able to use all its supported resources. Review every attached Vault first. A value hidden in the dashboard remains usable through an authorized runtime read. ## Invite one person Open the Custom Project's **Access > Manage sharing**, enter the intended account email, and choose **Invite**. The recipient reviews the invitation in the Notification Center and accepts or declines it. Follow [Share a Project](/guides/workflows/share-a-project) for the task steps and expected result. [Invite a Viewer](/guides/projects-and-sharing#invite-a-viewer) contains the CLI alternative. ## Create a share link Use **Create invite link** in the sharing dialog when you intend to distribute access yourself. Treat the active URL as an invitation that can be forwarded. Review [Share with a link](/guides/projects-and-sharing#share-with-a-link) for CLI creation, acceptance, and secure handling. Revoking a link stops future acceptance through that link. Accepted members retain their membership until you remove it. ## Use an accepted Project with an Agent After reviewing the Project, the recipient opens the intended Agent's **Projects** section and chooses **Link**. Confirm the Project appears among that Agent's linked resources. The teammate has Viewer membership, and the selected Agent has an explicit Project link. The owner retains control of the source content. The Agent's fixed Agent Project remains its default write target. For Connected Agents, use the [explicit Skill import workflow](/guides/skills#import-a-project-skill-into-a-connected-agent) to copy a Project Skill to the computer. Availability follows the [supported software table](/getting-started/connect-agents#supported-agent-software). ## Remove access Choose the scope that matches your goal: | Goal | Action and effect | | - | - | | Stop one Agent using a Project | Unlink the Project from that Agent; the person's membership remains. | | Stop future joins through one URL | Revoke that share link; existing members remain. | | Remove an accepted person | Remove their Viewer membership; future access and affected Agent Project links are removed. | | End all sharing | Revoke links, cancel pending invitations, and remove accepted Viewers. | | Leave someone else's Project | Remove your own membership and the access it provides. | Use [Stop sharing](/guides/projects-and-sharing#stop-sharing) for the canonical commands. Afterward, review the member, invitation, and share-link lists and the affected Agent's Projects to confirm the intended scope. The owner's Project content remains available to the owner. ## Review before sharing 1. Review every Skill and attached Vault; move sensitive resources to a separate Project before inviting someone who should have narrower access. 2. Use a directed invitation for a known account email. 3. Label share links so you can identify them later. 4. Review members, pending invitations, and active links after collaboration ends. 5. Unlink a Project from any Agent that has finished using it. # Changelog Source: https://docs.clawdi.ai/changelog Read curated, user-facing notes about notable Clawdi releases. Follow notable improvements to the current Clawdi experience. Availability can vary by Agent software, run path, account, and rollout status; use the current documentation and the [Clawdi dashboard](https://cloud.clawdi.ai) to see what is available to you. Looking for releases from the previous Cloud Agent product generation? See [Legacy Cloud Agents](/legacy-cloud-agents). ## Faster Cloud Agent setup, CLI 0.16, and sign-in from any terminal ### Clawdi CLI * CLI 0.16 keeps output human-readable unless you pass `--json`. JSON results from `doctor`, Session, Memory, Project, Wallet, AI Provider, and `deploy` commands use a new versioned format, so update scripts that read them. See [Scripting and automation](/cli/index#scripting-and-automation). * Starting with CLI 0.15.18, commands that delete or revoke something require `--yes` when no interactive terminal is available. Older aliases are removed: use `clawdi vault detach` and `clawdi agent projects unlink`. * If you installed the CLI with the native installer and use 0.15.8 or earlier, `clawdi update` can no longer update it. Reinstall once from [Install the Clawdi CLI](/installation). * If your background sync was installed before June 4, 2026, run `clawdi daemon install` again after updating to CLI 0.16. Very old installations may upload some Sessions or Skills again. * CLI versions before 0.15.0 must be updated before they can sign in. API keys can no longer be created in the dashboard; existing keys are listed with their permissions and expiry, and you can still revoke them. * Sign in with a browser link and short code, then let the CLI finish automatically. Setup explains what it enabled and links to your dashboard. * After you sign in with `clawdi auth login`, CLI 0.15.7 and newer can do what the dashboard can, apart from [a few browser-only actions](/account/authentication#cli-permissions). Manage Agents, Cloud Agent lifecycle and plugins, uploaded Sessions, Projects, and Cloud AI Providers from the terminal. * Inspect Wallet transactions and usage, unlink Channels or unpair chats, read Skills, and request secrets through a browser link. * Keep projects out of sync with `clawdi config set excludeProjects`, or exclude one before its first upload with `clawdi setup --exclude-project `. The installer adds the CLI to your `PATH`, and `NO_COLOR` or `--no-color` turns off color. * Install the CLI natively on Windows x64 and arm64 with the PowerShell installer, without Node.js. * Automatic updates wait at least 24 hours after a release; `clawdi update` still installs the newest version right away. * Pi supports MCP and Skills, and DeepSeek Harness Skills are supported. ### Cloud Agents * New Cloud Agents can be ready sooner: Clawdi keeps OpenClaw and Hermes Agents partly prepared in advance, so a new Agent skips most of its initial setup when one is available. * While a new Cloud Agent is being set up, you see its Overview behind a progress indicator. It opens once chat on the web is ready, and slow or failed setups offer a direct way to contact support. * New Hermes Cloud Agents finish setup again, and a Hermes Agent keeps running even if its dashboard can't start; Clawdi shows when the dashboard is unavailable. * If a custom provider you add in Clawdi overlaps one set up directly in Hermes or OpenClaw, your Agent keeps running and your own provider stays. * Chatting with a Hermes Agent through a Channel always counts as activity, so an Agent in use is not stopped as idle. * Agents keep running when a tool runs out of memory or when Clawdi updates them. * A Cloud Agent you stopped, or a free Agent stopped for inactivity, stays stopped when its plan renews. ### Agents and Sessions * An Agent's Overview lists its profiles, such as Hermes named profiles or OpenClaw agents, with their status and Session counts. Filter the Agent's Sessions by profile. Connected Agents need CLI 0.15.0 or newer. * Claude Code Session titles and renames sync, and Claude Code sub-agent transcripts and forked or sub-agent Codex threads appear as their own Sessions. Hermes Sessions with images sync, and Hermes, OpenClaw, and Pi transcripts show only the conversation. * `clawdi session list --uploaded` works again. ### Channels * When a linked Agent is offline, people who message it get a short reply saying so instead of silence. * Discord connection problems, such as a rejected bot token or disallowed intents, appear on the Channels page with steps to fix them. ### AI models and Providers * GPT-6.1 Sol is now featured in Managed AI. GPT-6 Sol remains available under all models. * When you switch to a provider that leaves the model choice to your Agent, AI Provider settings remind you to choose a model inside the Agent. ### Dashboard * Chat with Clawdi support from **Help > Live chat** in the dashboard. * Opening [notifications](/account/notifications) marks them read, and their links open inside the dashboard. ## New AI models, Agents that keep running, and easier Wallet payments ### AI models * GPT-6 Sol, GPT-6 Luna, and Grok 4.7 are now available in Managed AI and featured in the model list. GPT-6 Astra remains the recommended default. * GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, and Grok 4.6 are still available under all models. If your Agent uses one of them, nothing changes. * Switching your Agent's model, or getting newly added models, no longer restarts the Agent, so conversations in progress keep running. * Connect any compatible AI service as a Custom AI Provider with a name, address, and key, then choose models inside your Agent. Your model choices stay in place when you change the key. * AI Providers are grouped by brand, so the one you want is easier to find. ### Cloud Agents * A new Agent opens once it is fully ready, including right after checkout. * If part of your Agent can't be set up, such as a WhatsApp connection, the Agent shows what went wrong and how to fix it instead of appearing unreachable. * Files and your Agent's dashboard stay available even when another part of the Agent has a problem. * Agents recover more reliably after maintenance and no longer get stuck showing that they aren't ready. * Open the Hermes dashboard with your Clawdi account. A separate dashboard password is no longer needed. * The OpenClaw dashboard stays open while you move between Agent sections, signs you back in automatically, and opens web chat faster. * New Agents come with more built-in tools, such as Vim and tmux. ### Channels * Discord and Telegram messages reach your Agent faster, especially after it has been quiet for a while. * OpenClaw Agents with WhatsApp connected start reliably, and a problem with one Channel no longer affects your other Channels. * Unlinking WhatsApp from a Hermes Agent no longer leaves the Agent restarting. ### Sessions, Vault, and Connectors * Open Sessions update as new messages arrive, and jumping to a search result takes you straight to the message. * Ask your Agent to share a Session for you. * When your Agent needs a credential, it can send you a secure link to fill it in without signing in. Add extra fields or paste or upload a `.env` file, then review everything before saving. * Vault values can be kept in sync as files in your Agent's workspace. * Connect several accounts to the same Connector and give each one a name. Your Agent can add, rename, or remove them for you. ### Wallet * Top up your Wallet with a saved card, Apple Pay, Google Pay, or Link. * Cards you have already saved appear automatically, and one **Edit** button manages them. * Wallet transactions show how each payment was made: card, Wallet, or USDC. ### Free Cloud Agents * A free Cloud Agent that receives no messages for 7 days is stopped after an email warning. You can start it again at any time. * If it stays unused, you receive another email, and the Agent is permanently deleted after 30 days without messages. * Sending your Agent a message resets this timer. Opening the dashboard or starting the Agent does not. ### Clawdi CLI * Clawdi installed with Homebrew updates through Homebrew. * Background sync on Windows no longer needs administrator rights. * Skills stored in linked folders are found and loaded. ## Share conversations, add Skills, and connect more AI Providers ### Sessions and search * Share a snapshot of a whole Session, the conversation up to a chosen message, or just one Agent response. New messages are not added to the snapshot; private reasoning and tool payloads stay out of shared content. * Review, copy, open, and turn off active links from **Shared Session links**. Older live links are clearly distinguished from snapshots. * Read messages and Agent activity in one chronological timeline, jump to the latest messages, and keep the Session's context and search controls within reach in long conversations. * Find Sessions with multiple search terms and search very long messages more reliably. Project, Agent, Skill, Vault, and Connector search also shows more relevant results with clearer matching context. ### Skills and shared resources * Install Skills from Library or a public GitHub repository from an Agent's **Skills** section. Review source details and installation status, follow Library updates, and remove installed Skills. Supporting files stay with the Skill. Availability depends on the Agent software and update status; existing Cloud Agents receive this through their managed updates. * Browse **Linked** and **Available** Projects and Vaults together, with direct **Link** and **Unlink** actions from the Agent or Project you are working in. * Create Projects and Skills, manage linked Vaults and Connectors, and pair chats or repair a WhatsApp connection from the relevant Agent or Project page. * Ask an Agent to review, update, or delete a specific Memory, browse past Sessions, or create a Vault and manage individual fields where its Project access allows. Agents can also check which connected service account they will use before taking action. ### AI Providers * Managed AI adds GLM-5.3 and makes GPT-6 Astra the recommended default for new selections. * Connect your own provider key or a supported ChatGPT account without first setting up a model list or default model in Clawdi. Choose models in Hermes or OpenClaw, with existing model choices and saved credentials preserved. * Choose from more supported providers, including NVIDIA NIM, Fireworks, Hugging Face, DeepInfra, OpenCode Zen and Go, Xiaomi MiMo, and Tencent TokenHub and TokenPlan. Setup shows provider logos and credential links. ### Notifications and Compute * See account updates alongside invitations in the notification center. These include Wallet and automatic top-up alerts and account status updates. Browse older notifications, filter unread items, mark items read or unread, mark all as read, and delete notifications you no longer need. * Eligible accounts can try Compute with their first card-funded Basic or Performance subscription. This one-time trial replaces the free Basic allowance for new accounts; existing included Basic capacity is preserved. Wallet-funded subscriptions do not include the trial, and a card cannot be reused to claim another trial. Checkout shows the current trial terms and subsequent billing. * Checkout retries preserve trial eligibility more reliably, and cancelling during the trial ends it immediately. Subscription and Agent status make payment processing, cancellation, and the next action clearer. ### Clawdi CLI 0.14.57 * Share a whole Session, the conversation up to a chosen message, or one response from the CLI. List and turn off active links, or export a Session without making it public. * Update an existing Memory while preserving its category and source. * Inspect, install, and remove supported Cloud Agent Skills from GitHub or Library, with clear installation status and failure feedback. * Deploy with native saved AI Providers without supplying a model. Older scripts that pass a model still work; choose models inside the Agent. ### Everyday improvements * Reach the Agent's own dashboard, messaging Channels, and AI Provider more easily from its overview, alongside recent Sessions and a clearer Compute and subscription summary. * Recover a Connected Agent's lost local connection with `clawdi agent reconnect` while keeping its existing Agent identity. Signing out and back into the same account also preserves local Agent registrations. Reconnecting asks before taking over a recently active connection on another computer. * Telegram media downloads and Discord reconnections are more reliable. OpenClaw and Hermes Session sync handles larger histories more smoothly, and Cloud Agent updates avoid unnecessary restarts. * Cloud Agent Terminal handles command startup more reliably and displays Chinese and other non-ASCII text correctly during continuous output. * Newly created Cloud Agents support compatible tools for mounting external filesystems and retain Files settings and local sync state more reliably through updates. Older Agents need a compatible Cloud Agent update. * Dashboard navigation, Connector browsing, and Session search are faster and more responsive. * The older dashboard now points to the current dashboard and Agent creation flow. Portrait continues to show activity, but no longer generates mecha artwork. ## Search Sessions and expand Agent capabilities * Search visible user and assistant message text from the Sessions list, see the best matching excerpt, and open the Session at that message. Private reasoning, system messages, and tool payloads stay out of search results. * Search within an open Session, move between matches with the controls or keyboard, and keep the matching text highlighted while you read. * Open a Cloud Agent's Terminal in a standalone browser window. The Terminal fills the window and keeps its scrollback during supported reconnects. * Connect Pi or OpenCode on your computer to sync its Sessions into Clawdi. These integrations focus on Sessions and do not configure Skills or MCP. * Synced Sessions can preserve structured tool activity and private reasoning when the Agent software provides it. Sharing, search, and Memories continue to use visible conversation content rather than private reasoning. * OpenClaw Cloud Agents can use a separate managed embedding model for memory search without changing the AI Provider or model used for chat. The setting follows managed runtime updates and clears with the managed provider. ## Cloud Agents gain Plugins and clearer live status * Browse, search, and filter Plugins from a Cloud Agent's **Plugins** section, with compatibility shown for the Agent software it runs. * Install, update, retry, or remove supported Plugins and follow their status until they are ready to use. * See start, stop, restart, settings, and deletion progress without repeatedly refreshing the page. * Agent status and Channel health avoid reporting readiness too early and use clearer wording when current details are unavailable. ## Search Cloud Sessions from the CLI * Use `clawdi session search` to find uploaded Session metadata by keyword and narrow results by Agent or activity date. Search covers summaries, Project paths, and Session IDs rather than message text. * Use a result's Cloud Session ID with `clawdi session read` to open its uploaded messages. ## Manage Project access across Agents * Link multiple Projects to an Agent in one change, or manage the Agents that use a Project from the Project page. * A linked Agent can use the Project's Skills and attached Vaults together as one resource bundle. ## Delete synced Sessions * Permanently delete a synced Session's Cloud copy and prevent it from syncing again. Local data and extracted Memories remain. ## Hosted V2 launches publicly Clawdi launched the current Hosted V2 Cloud Agent experience publicly. * Open a Cloud Agent's private Workspace from **Files** in the dashboard or a new tab when file access is available for the Agent. * Connect a custom WhatsApp account through linked-device onboarding, then link an Agent, pair a chat, or repair the connection as separate actions. * Manage compute subscriptions in one account-wide view and load older subscriptions as needed. * Review unified Wallet and card-funded transaction history, including receipt or invoice links when available, and use the payment methods offered by the current top-up flow. * Keep managed AI Provider and model configuration consistent across Hermes and OpenClaw runtime updates. * Find shared resources under **Library**, including integrations such as Channels, Connectors, and AI Providers. ## Cloud Agents join the shared Clawdi experience Clawdi introduced the current Cloud Agent run path for creating and running supported Agent software remotely, alongside Agents connected from your own computer. * Create a Cloud Agent from the dashboard or the Clawdi CLI, then manage it from its Agent page. * Open the interface provided by the Agent software or use its Terminal when the remote runtime is ready. * Keep supported workspace files, plugins, user configuration, and user-level tools across normal restarts and Clawdi platform updates. * Manage lifecycle actions, runtime settings, Sessions, Skills, AI Providers, and supported Channels from the same Clawdi account. * Continue using Connected Agents without moving them to the Cloud Agent run path. # CLI commands Source: https://docs.clawdi.ai/cli/commands Find the Clawdi command or command family for a common task. Use this page to find a command, then run `clawdi --help` for the arguments, options, and examples shipped with your CLI version. Object names follow the definitions in [Core concepts](/concepts/core-concepts). The Session sharing/export, Memory update, remote Skill management, and native provider deployment workflows require CLI **0.14.57 or newer**. Check `clawdi --version` and [update the CLI](/installation/update) when needed. Self-hosted services also need the corresponding API support. Use CLI **0.15.7 or newer** for the new Agent, uploaded Session, Wallet, and Cloud resource commands below. Examples follow CLI **0.16**, where scripts pass `--json` explicitly and confirm destructive commands with `--yes`; see [Scripting and automation](/cli/index#scripting-and-automation). ## Get started and stay healthy | Command | Purpose | | - | - | | `clawdi auth login` / `logout` | Add or remove this computer's authentication | | `clawdi auth status` | Show the credential source without printing secrets | | `clawdi setup` | Detect Agent software, register Connected Agents, add MCP, install the bundled Skill, and install the daemon | | `clawdi teardown` | Reverse Connected Agent setup | | `clawdi agent reconnect` | Restore a lost local connection to an existing Agent | | `clawdi status` | Show authentication and sync activity | | `clawdi doctor` | Diagnose authentication, reachability, Agent paths, Vault metadata, and MCP | | `clawdi update` | Install the latest CLI version; use `--check` to report only | ## Manage Agents | Command | Purpose | | - | - | | `clawdi agent list` | List your Connected Agents and Cloud Agents, their full IDs, and last activity | | `clawdi agent rm ` | Disconnect a Connected Agent and archive its workspace, or permanently delete a Cloud Agent and its saved data | | `clawdi agent start ` | Start a Cloud Agent and wait for completion | | `clawdi agent stop ` | Stop a Cloud Agent and wait for completion | | `clawdi agent restart ` | Restart a Cloud Agent and wait for completion | | `clawdi agent plugins list ` | List requested Cloud Agent plugins and whether they have been applied | | `clawdi agent plugins install ` | Request installation of a plugin from the catalog | | `clawdi agent plugins rm ` | Request removal of a Cloud Agent plugin | Use the Agent UUID from `clawdi agent list`. For lifecycle commands, `--no-wait` returns when the server accepts the operation. Plugin changes return when accepted; check `agent plugins list` to confirm they were applied. ```bash theme={null} clawdi agent list --json clawdi agent rm --yes clawdi agent rm --yes --cancel-subscription clawdi agent start --no-wait clawdi agent stop --no-wait clawdi agent restart --no-wait clawdi agent plugins list --json clawdi agent plugins install clawdi agent plugins rm --yes ``` Removing a Cloud Agent permanently deletes its deployment and saved data. A renewing subscription requires a choice: `--cancel-subscription` cancels it, or `--keep-subscription` keeps it for a future Agent. Non-interactive removal requires `--yes` and, for a renewing subscription, one of those options. ## Sync and inspect Agent data | Command | Purpose | | - | - | | `clawdi push` | Upload Connected Agent Sessions and Skills available to sync | | `clawdi pull` | Mirror Sessions or explicitly import an eligible Project Skill | | `clawdi session list` | List local Connected Agent Sessions | | `clawdi session list --uploaded` | List Sessions already uploaded to Clawdi | | `clawdi session rm ` | Permanently delete an uploaded Session | | `clawdi session search` | Search uploaded message text, summaries, folders, and IDs | | `clawdi session read` | Read an uploaded Session using its Cloud Session ID | | `clawdi session export` | Export an uploaded Session without publishing a link | | `clawdi session share` | Create a public snapshot of a whole conversation or selected portion | | `clawdi session shares` / `unshare` | List and revoke active Session links | | `clawdi session extract` | Extract Memories from a local Session through Clawdi | | `clawdi daemon status` | Inspect the background sync daemon | | `clawdi daemon logs` | Read daemon logs | | `clawdi daemon restart` | Restart the daemon after refreshing setup | Use the uploaded Session UUID from `session list --uploaded` for removal: ```bash theme={null} clawdi session list --uploaded --limit 10 --json clawdi session rm --yes ``` ## Work with shared context | Command family | Purpose | | - | - | | `clawdi memory` | List, search, add, update, and remove Memories | | `clawdi skill` | Manage local Connected Agent Skills and Project Skills | | `clawdi skill show ` | Read a Project Skill without importing it | | `clawdi agent skills` | Inspect, install, and remove Skills on an explicitly selected Cloud Agent | | `clawdi project` | Create, inspect, share, and manage Projects | | `clawdi project rm ` | Archive a Project you created | | `clawdi inbox` | Review and respond to Project invitations or share links | | `clawdi agent projects` | List, link, unlink, or move Projects for an Agent | Use [Sessions](/guides/sessions) for share scopes and link IDs, and [Skills](/guides/skills) for the distinction between local software names, Cloud Agent IDs, and Library Skill IDs. Manage account notifications and payment details through the dashboard. ```bash theme={null} clawdi skill show --project --json clawdi project rm --yes ``` Use `link` and `unlink` for Agent Project access. `attach` and `detach` remain compatible aliases for existing scripts. ## Work with secrets and AI Providers | Command family | Purpose | | - | - | | `clawdi vault` | Manage Vault keys, attachments, imports, and references | | `clawdi vault request ` | Create a browser link for supplying a secret without the CLI reading its value | | `clawdi read ` | Explicitly print one resolved Vault value | | `clawdi inject` | Render `clawdi://` references into an output file | | `clawdi run` | Run a child command with explicit Vault references resolved | | `clawdi ai-provider` | Manage Cloud AI Providers, local catalog entries, and credential references | | `clawdi ai-provider list` | List Cloud AI Providers and local catalog entries | | `clawdi ai-provider edit ` | Update a Cloud AI Provider or local catalog entry | | `clawdi ai-provider remove ` | Remove an AI Provider, confirming any affected Cloud Agents | After sign-in, `ai-provider list`, `edit`, and `remove` work with Cloud AI Providers. The local catalog remains available for import and export; without sign-in, `list` shows only local entries. Use the provider ID from `ai-provider list` for edits and removal. `vault request --wait` waits up to five minutes for the secret to be supplied. The Vault must already be attached to the selected Project. ```bash theme={null} clawdi ai-provider list --json clawdi ai-provider edit --label "Main" --json clawdi ai-provider remove --yes clawdi vault request /OPENAI_API_KEY --project --wait ``` `clawdi read` and non-dry-run secret commands can expose plaintext to the terminal or a child process. Prefer `--dry-run` first and avoid placing secret values directly in command-line flags. ## Inspect your Wallet | Command | Purpose | | - | - | | `clawdi wallet transactions` | List Wallet transactions | | `clawdi wallet usage` | Show usage for the reporting period; select days with `--days` | | `clawdi wallet portal` | Print the dashboard billing URL | ```bash theme={null} clawdi wallet transactions --limit 20 --json clawdi wallet usage --days 7 --json clawdi wallet portal ``` ## Deploy a Cloud Agent | Command family | Purpose | | - | - | | `clawdi deploy` | Create a remotely running Agent with the interactive deployment wizard | This workflow is available only for Cloud Agents. Run `clawdi deploy --help` for current choices and automation requirements. See [Automate Cloud Agent deployment](/cloud-agents/deployment-automation). ## Work with Channels and MCP | Command family | Purpose | | - | - | | `clawdi channel` | Manage Channel bots, Agent links, chat pairing, and messages | | `clawdi channel unlink ` | Unlink an Agent using its Channel link UUID | | `clawdi channel unpair ` | Unpair one chat using its binding UUID | | `clawdi mcp` | Start the MCP stdio server used by configured Agents | ```bash theme={null} clawdi channel unlink --link --yes clawdi channel unpair --binding --yes ``` Connectors are managed in the [Clawdi dashboard](https://cloud.clawdi.ai), not with a CLI command. ## Configure the CLI ```bash theme={null} clawdi config list clawdi config get clawdi config set clawdi config unset clawdi config paths ``` Use `clawdi config paths` to identify the local paths used by the current CLI installation. Do not edit generated or credential files unless a specific troubleshooting guide tells you to. For the complete command list, see `clawdi --help` and the [current CLI reference in the Clawdi repository](https://github.com/Clawdi-AI/clawdi#cli-reference). # Clawdi CLI Source: https://docs.clawdi.ai/cli/index Manage Connected Agents and Cloud Agents, work with shared context, and automate Clawdi tasks. The `clawdi` CLI is the main interface for adding an Agent that runs on your computer. It registers Connected Agents, installs supported MCP integration, syncs supported data, works with shared Clawdi objects, and controls the background daemon. With CLI **0.15.7 or newer**, you can also list and manage Agents, control Cloud Agent lifecycle and plugins, manage uploaded Sessions and Cloud AI Providers, and inspect Wallet transactions and usage. Use `clawdi deploy` to create a Cloud Agent. See [CLI commands](/cli/commands) for examples and [Authentication](/account/authentication#cli-permissions) for access limits. Scripting guidance below follows CLI **0.16**. ## Discover commands Every command provides built-in help: ```bash theme={null} clawdi --help clawdi setup --help clawdi memory --help clawdi memory add --help clawdi deploy --help ``` Use the deepest relevant `--help` command before scripting flags. The CLI help shipped with your installed version is the most precise reference for that version. ## Check local state These commands do not print stored secret values: ```bash theme={null} clawdi auth status clawdi status clawdi doctor clawdi daemon status ``` * `auth status` identifies the current credential source. * `status` summarizes authentication and sync activity. * `doctor` checks authentication, API reachability, Agent paths, Vault metadata, and MCP configuration. * `daemon status` reports the background sync service state. ## Preview sync and secret actions Use dry-run modes when a command supports them: ```bash theme={null} clawdi push --dry-run clawdi pull --dry-run clawdi run --dry-run --env-file .env.clawdi -- npm run dev ``` For secret workflows, `--dry-run` checks reference provenance without requesting plaintext values. ## Scripting and automation ### Use machine-readable output Commands that advertise `--json` return machine-readable output. Confirm support on the exact command before using it in automation. Starting in CLI **0.16**, pass `--json` explicitly: piped output stays human-readable. JSON output is one object with a string `schemaVersion`, such as `"clawdi.agentList.v1"`, and lists appear in a named array inside the object. CLI 0.16 moved `doctor`, `session list`/`search`, `memory list`/`search`, `project list`, `deploy`, `wallet status`/`transactions`/`usage`, and `ai-provider list`/`export` to `v2` objects; update scripts that read them. Results go to stdout; errors, progress, and prompts go to stderr. Check the exit code and allow additional fields when parsing versioned output: ```bash theme={null} clawdi agent list --help clawdi agent list --json ``` ### Confirm destructive actions Pass `--yes` to confirm destructive commands in scripts. `--json` does not imply confirmation. Starting in CLI **0.15.18**, commands that delete or revoke something require `--yes` without an interactive terminal. ```bash theme={null} clawdi session rm --yes --json ``` ### Check exit codes | Exit code | Meaning | | - | - | | `0` | Success | | `1` | Command or API error | | `2` | `session extract` is not configured | | `4` | Sign-in is required; run `clawdi auth login` | ### Control color and updates Set a non-empty `NO_COLOR` environment variable or pass `--no-color` to disable color. Every command accepts `--no-color` before the `--` separator. Opt out of CLI and daemon background auto-updates with `CLAWDI_NO_AUTO_UPDATE=1`, or save the preference: ```bash theme={null} clawdi config set autoUpdate false ``` Find the command family for a common task. Understand the objects named in commands and output. Diagnose sign-in, setup, MCP, and daemon problems. # Agent Interface, Files, and Terminal Source: https://docs.clawdi.ai/cloud-agents/agent-interface-and-terminal Use a Cloud Agent's browser interface, Workspace files, and Terminal with clear readiness and persistence boundaries. Open **Agents** in the [Clawdi dashboard](https://cloud.clawdi.ai), select the Cloud Agent, then open its **Hermes Dashboard** or **OpenClaw Control UI**, **Files**, or **Terminal**. These tools belong to the remote runtime and are available only for Cloud Agents. **Files** appears when file access is available for that Agent. ## Agent Interface The Agent interface embeds **Hermes Dashboard** or **OpenClaw Control UI**. Its layout, capabilities, and authentication can differ by software. The Agent overview also links to its messaging Channels and AI Provider settings. 1. Confirm the Cloud Agent is **Running** and open **Hermes Dashboard** or **OpenClaw Control UI**. 2. Wait for the embedded interface to load; open **Access** only when sign-in material is needed. 3. Start a new conversation and send a small, non-secret task. 4. Review the response before trusting a larger workflow. The embedded interface accepts your task and shows a response from the intended Cloud Agent. Hermes Dashboard inside Clawdi with rendered terminal startup content, available tools, and New chat control. Hermes Dashboard inside Clawdi with rendered terminal startup content, available tools, and New chat control. *The Chat workspace shows rendered terminal startup content and available tools. Account identity, private runtime session metadata, and terminal input are masked for privacy. The loaded-model label remains visible. Use New chat for your own task.* ### Hermes models In **Chat**, open the current model selector to review the loaded model catalog and the model choices available to this runtime. Model availability can change with the Agent's AI access configuration. Hermes model picker inside Clawdi with the loaded Clawdi model catalog and selectable model rows. Hermes model picker inside Clawdi with the loaded Clawdi model catalog and selectable model rows. *The native model picker shows the loaded Clawdi catalog in the running Hermes interface.* [Light full-size image](/assets/clawdi-demo-screenshots/light/hermes-models.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/hermes-models.webp) ### OpenClaw Control UI An OpenClaw Cloud Agent opens its own **OpenClaw Control UI**. Wait for the runtime connection and model catalog to load before beginning a conversation. OpenClaw Control UI inside Clawdi at the native /new frame, with a connected runtime and loaded model catalog. OpenClaw Control UI inside Clawdi at the native /new frame, with a connected runtime and loaded model catalog. *The OpenClaw screenshot shows a connected runtime at `/new` with the model catalog loaded. This ready-to-start view illustrates interface readiness; task verification follows after you send your own request.* [Light full-size image](/assets/clawdi-demo-screenshots/light/openclaw-dashboard.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/openclaw-dashboard.webp) * The Cloud Agent must be **Running**. * The interface endpoint can become ready after the runtime starts. If the page says it is not ready, choose **Check again** or use Terminal while it starts. * **Access** shows the current software-specific sign-in material when one is required. Treat a displayed password or token as a secret. * **Open in new window** can require your browser to allow pop-ups for Clawdi. * **Reset access** rotates the current access material and restarts the whole Agent through its normal lifecycle. Existing Agent Interface windows can no longer use the old material. ## Files **Files** opens the Cloud Agent's private Workspace in an embedded browser. The Agent must be **Running**, and Clawdi authenticates the Files session before the Workspace loads. Choose **Open in new window** when you need the same Files view outside the Agent page. Twelve synthetic long-term Workspace files in a Cloud Agent Files view Twelve synthetic long-term Workspace files in a Cloud Agent Files view *Workspace files can hold recurring reviews, decision logs, calendars, and research history.* If **Files** is not shown, file access is not available for that Agent. Use Terminal or the Agent Interface for the runtime workflow available to it. ## Terminal **Terminal** opens a secure shell session for the Cloud Agent. It is available only while the Agent is **Running**. Choose **Open in new window** for a standalone Terminal. Supported reconnects preserve scrollback, but do not assume a disconnected foreground command is still running. The status above the Terminal reports **Connecting**, **Connected**, or **Disconnected**. If a connection closes, choose **Reconnect** to request a new session. Starting, stopping, restarting, updating, or deleting the Cloud Agent can close an active session. The shell runs as the ordinary runtime user, not with unrestricted system administrator access. Some protected system paths, operating-system package operations, and service-level changes can therefore be unavailable. The Terminal does not bypass Clawdi access controls, an Agent software permission model, or an external service's authorization. ## What persists The durable boundary is narrower than an entire operating system image. | Designed to persist | Not durable | | - | - | | Supported workspace files | The Terminal connection itself | | Supported Agent plugins and user configuration | A running foreground shell process, temporary files, or runtime scratch data | | Supported user-level tools | Arbitrary changes to protected operating-system files, packages, or services | Supported workspace files, plugins, user configuration, and user-level tools are preserved across normal restarts and Clawdi platform updates. This does not guarantee persistence for every filesystem path or operating-system change, and it does not provide automatic version control or backup. Deleting the Cloud Agent permanently removes its remote resources. Do not keep the only copy of important work in the remote runtime. Use source control or another appropriate external system for important project files. Use [Vault](/concepts/core-concepts#vault) for supported secret workflows instead of pasting secrets into shell history, logs, or source files. If a live tool is unavailable, see [Cloud Agent troubleshooting](/cloud-agents/troubleshooting#agent-interface-files-and-terminal). # Choose AI for your Cloud Agent Source: https://docs.clawdi.ai/cloud-agents/ai-access Choose AI access and, when required, a primary model for a Cloud Agent. Open a Cloud Agent’s **AI Providers** to choose the AI service it uses for your tasks. ## Access modes | Choice | Behavior | Billing | | - | - | - | | **Clawdi AI** | Choose from the Clawdi catalog. | Uses the account Wallet. | | **Saved AI Provider** | Connect saved credentials; choose models inside the Agent for supported native connections. Custom catalogs can require a model here. | Billed by the provider. | | **Configure inside agent** | Configure model access after startup. | Depends on that service. | Available providers and models depend on the Agent software and runtime. ## During deployment 1. Choose the Agent software. 2. Choose **Clawdi AI**, a saved provider, or **Configure inside agent**. 3. Select a primary model when required. 4. Review and deploy. For command-line setup, see [deployment automation](/cloud-agents/deployment-automation). ## Change a running Agent 1. Open the Agent's **AI Providers**. 2. Choose **Clawdi AI**, a saved provider, or **Configure inside agent**. 3. Select a model when the page asks for one, then choose **Save changes**. 4. Wait for the update to finish, open the Agent's chat, and try a small task. Agent AI Providers with Clawdi AI, Configure inside agent, Add a provider, and model choices. Agent AI Providers with Clawdi AI, Configure inside agent, Add a provider, and model choices. *Choose how this Cloud Agent accesses AI. The available models can change.* For a native saved connection, select models in **Hermes Dashboard** or **OpenClaw Control UI**. You do not need to build a model list in Clawdi first. Connecting the credential preserves existing Agent model choices. Clawdi AI continues to require a model from its current catalog. Manage saved keys, supported account sign-ins, and custom endpoints under **Library > AI Providers**. See [AI Providers](/guides/ai-providers#configure-a-cloud-agent-provider) for the connection steps. Connected Agent and Cloud Agent provider settings are separate. When a provider becomes unavailable, choose another provider, Clawdi AI, or configuration inside the Agent. See [troubleshooting](/cloud-agents/troubleshooting#ai-access-and-models). # Choose your Cloud Agent setup Source: https://docs.clawdi.ai/cloud-agents/choose-your-setup Choose Hermes or OpenClaw, AI access, compute, and preferences before you deploy a Cloud Agent. Use this optional guide if you are unsure what to select in the deployment wizard. If the choices already make sense, continue with the quickstart. Options, offers, and availability can vary. The signed-in deployment wizard is the authority for what you can select and the exact terms you are asked to confirm. ## Choose Agent software **Agent software is separate from the Cloud Agent run path.** Cloud Agent describes where the Agent runs and who manages its runtime. Agent software determines the interface and workflows you use with that Agent. When these options appear, the released wizard describes them this way: | Agent software | Choose it when | | - | - | | **Hermes** | You want the option recommended for most people and plan to chat with and manage the Agent in the Hermes Dashboard. | | **OpenClaw** | You already use OpenClaw and want its Control UI and workflows. | Do not infer availability if an option is not shown. Make this choice before AI access because the providers and models you can use can depend on the selected Agent software. ## Choose AI access and a model Decide whether to use Clawdi AI, a saved AI Provider shown as usable, or model access that you configure inside the Agent after deployment. Choose a primary model when the wizard asks for one. Supported native saved connections need only credentials here; choose their models inside Hermes or OpenClaw. Read [Configure Cloud Agent AI access](/cloud-agents/ai-access) for the differences between these paths, including how Clawdi AI and external provider usage are handled. ## Choose compute Compare the resources, current price, billing terms, and availability shown in the wizard against the work you expect the Agent to do. For a paid choice, review the funding method and exact confirmation shown before continuing. Compute and model usage are separate cost boundaries. The live wizard and the Agent's settings are the sources of truth for current compute offers; this documentation does not reproduce them. See [Cloud Agent usage and billing](/cloud-agents/usage-and-billing) for the durable billing boundaries. ## Personalize the Agent Choose a recognizable name, then review the language and timezone the Agent should use. You can review language and timezone later in the Agent's **Settings**. These preferences do not change the run path or Agent software. ## Review before you deploy Check that the summary shows the intended Agent software, AI access and model, compute choice, name, language, and timezone. Review any payment confirmation, then submit the deployment once and return to the [Cloud Agent quickstart](/cloud-agents/deploy) to wait for **Running**. # Cloud Agent quickstart Source: https://docs.clawdi.ai/cloud-agents/deploy Deploy a Hermes or OpenClaw Cloud Agent from the dashboard. Create a managed Agent from the Clawdi dashboard. The CLI and local Agent software are optional. ## Before you begin * Sign in to the [Clawdi dashboard](https://cloud.clawdi.ai). * Confirm that **Deploy a Cloud Agent** is available. * Review the available software, AI access, compute, and price options. See [Choose your Cloud Agent setup](/cloud-agents/choose-your-setup) for help with these choices. ## Steps Choose **New agent**, then **Deploy a Cloud Agent**. Name the Agent and choose Hermes or OpenClaw. Choose AI access and compute, then continue to review the current price and checkout terms. Confirm once. Deploy an Agent with software, AI access, model, and compute choices. Deploy an Agent with software, AI access, model, and compute choices. *Choose the setup that fits your task. Current prices and offers appear at checkout.* Open the Agent page and wait for **Running**. **Starting** is expected. For **Failed** or unclear states, see [states and recovery](/cloud-agents/states-and-recovery). Open **Hermes Dashboard** or **OpenClaw Control UI**, wait until it is ready, then send a small task: > Turn these notes into a checklist: choose a date, invite the team, and prepare an agenda. The Agent shows **Running** and responds in Agent Interface. ## Next steps Add a reusable fact or preference. Authorize an app and verify its tools. Learn access and persistence boundaries. Invite a teammate to reusable instructions and resources. Use [Automate Cloud Agent deployment](/cloud-agents/deployment-automation) for CLI creation, idempotency, and recovery guidance after your first dashboard deployment. # Automate Cloud Agent deployment Source: https://docs.clawdi.ai/cloud-agents/deployment-automation Use the CLI for repeatable Cloud Agent deployment and handle ambiguous outcomes safely. This guide is for operators and scripts. For a first Agent, use the [dashboard quickstart](/cloud-agents/deploy) instead. ## Before you begin * Install a released Clawdi CLI and check the version-specific command help. * Use browser authorization. A legacy manually entered API key does not authorize Cloud Agent deployment. * Decide whether this is one logical deployment attempt or an intentionally different deployment before assigning its request ID. ## Run the interactive CLI wizard Sign in with the browser authorization flow, confirm the credential source, then start the wizard: ```bash theme={null} clawdi auth login clawdi auth status clawdi deploy ``` In a headless environment, use the non-opening browser flow shown by `clawdi auth login --help`. Do not use `clawdi auth login --manual` for Cloud Agent deployment. The CLI loads the Agent software, AI access, model, compute, and payment choices currently available to the signed-in account. Before automating, read the help shipped with that CLI version: ```bash theme={null} clawdi deploy --help ``` Supply the choices required by the current help output and never put provider secrets on the command line. A saved provider ID refers to **Library > AI Providers**, not the local `clawdi ai-provider` catalog. With a supported native saved connection, omit `--model` and select the model inside Hermes or OpenClaw after startup. Clawdi AI and custom model catalogs still need a suitable model. Check `clawdi deploy --help` after updating the CLI. Card payment opens secure browser checkout; enter card details there. Trial eligibility and duration come from that checkout. Wallet-funded Compute has no card trial. If your authorization cannot purchase Compute, follow the CLI's Web Deploy Wizard handoff instead of retrying with another credential type. ## Make non-interactive retries idempotent Every non-interactive deployment requires a caller-supplied stable UUID in `--request-id` before the CLI sends a create or checkout mutation. Treat that UUID as the identity of one logical deployment attempt. * Reuse the same request ID, selections, and payment intent when retrying an attempt whose outcome is unclear. * Use a new request ID when you intentionally change the Agent software, AI access, compute, payment, or another deployment choice. * If the CLI reports a timeout or network error, the request may already have been accepted. Check **Agents** in the dashboard before retrying the same logical attempt with the same request ID. * If checkout is pending, complete or recover that checkout instead of starting a second payment. Use `--json` for automation. Its top-level result status distinguishes: | Result | Meaning | | - | - | | `authorization_required` | Sign in, then retry the same logical attempt. | | `payment_required` | Secure checkout still needs user action. | | `accepted` | Clawdi accepted the request; the Agent can still be starting. | | `succeeded` | The CLI observed the Agent become ready before returning. | | `error` | Read the safe error code and message before deciding whether to retry. | These result values are not the Agent's lifecycle status. After acceptance, use the dashboard as the status authority and follow [Cloud Agent states and recovery](/cloud-agents/states-and-recovery). ## Recover an unclear outcome 1. Keep the original request ID and deployment choices. 2. Open **Agents** and check whether the deployment already exists. 3. Recover any pending checkout rather than creating another payment intent. 4. Re-authenticate if needed, then retry only the same logical attempt. 5. After acceptance, wait for the Agent's lifecycle status instead of using a new request ID to work around a transition. For customer-visible failures after acceptance, use [Cloud Agent troubleshooting](/cloud-agents/troubleshooting). # Cloud Agents Source: https://docs.clawdi.ai/cloud-agents/overview Learn when to use a Hermes or OpenClaw Cloud Agent and how to deploy and manage it. A **Cloud Agent** runs on Clawdi. Open it from your browser and keep working while Clawdi manages the computer it runs on. Cloud Agent describes **where the Agent runs**. It does not identify the Agent software or make shared Clawdi capabilities exclusive to this run path. Read [Core concepts](/concepts/core-concepts) to learn how Agent, Project, Memory, Session, Skill, Vault, Connector, Channel, and AI Provider work across Clawdi. ## Choose a run path | Question | Connected Agent | Cloud Agent | | - | - | - | | Where does the Agent run? | On your computer | In a remote runtime managed by Clawdi | | Who operates the runtime? | You | Clawdi | | Must that computer remain available for the Agent to keep running? | Yes | No | | How do you add it? | `clawdi setup` | Dashboard deployment wizard or `clawdi deploy` | | Where do you use runtime tools? | In your local Agent software | **Hermes Dashboard** or **OpenClaw Control UI**, **Files** when available, and **Terminal** | Choose a Cloud Agent when independence from your computer and dashboard lifecycle controls matter more than unrestricted control of a local machine. Choose a Connected Agent when the Agent must work directly with your computer, its local tools, or a locally managed software installation. Continue with [Connect a local Agent](/getting-started/quickstart) if that path fits. Agent software is a separate choice. The deployment wizard currently offers Hermes and OpenClaw when they are available for the account. A Hermes Cloud Agent uses the Hermes experience; an OpenClaw Cloud Agent uses OpenClaw's Control UI and workflows. Tool and integration availability can vary by software and runtime state. ## What Clawdi manages For a Cloud Agent, Clawdi manages the remote runtime, its deployment state, compute selection, and start, stop, restart, and delete workflows. The Agent page also provides the browser interface exposed by the selected Agent software, Workspace file access when available, and a Terminal for the remote environment. Cloud Agent overview with recent Sessions, runtime status, and linked resources. Cloud Agent overview with recent Sessions, runtime status, and linked resources. *Open the Agent overview to check its status and continue your work.* [Light full-size image](/assets/clawdi-demo-screenshots/light/agent-overview.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/agent-overview.webp) Keep an external backup of important work. Read [Agent Interface, Files, and Terminal](/cloud-agents/agent-interface-and-terminal) for what stays available when you stop, restart, or delete an Agent. ## Add reusable tools Open **Plugins** to browse packages for this Cloud Agent. Review the publisher, version, included Skills, and tool connections before choosing **Install**. Follow [Add tools with Plugins](/guides/plugins) for the steps. ## Follow the journey Deploy from the dashboard and complete your first task in the Agent Interface. Compare Agent software, AI access, compute, and preferences before you deploy. Use the CLI, stable request IDs, and safe handling for an ambiguous attempt. Distinguish deployment state from tool readiness and respond safely to failures. Use browser tools within the remote runtime's persistence and permission boundaries. Change runtime settings and safely start, stop, restart, or delete the Agent. Bind the remote runtime to Clawdi AI, a saved AI Provider, or in-Agent configuration. Separate compute, Wallet activity, Clawdi AI usage, and external provider usage. If something is not behaving as expected, use [Cloud Agent troubleshooting](/cloud-agents/troubleshooting). # Cloud Agent settings and lifecycle Source: https://docs.clawdi.ai/cloud-agents/settings-and-lifecycle Change remote runtime settings and safely start, stop, restart, or delete a Cloud Agent. Open **Agents**, select the Cloud Agent, then choose **Settings**. This page combines Agent profile settings with controls that apply specifically to its remote runtime. ## Change runtime settings The current settings surface can include language and timezone, compute, lifecycle, and deletion controls. AI access is managed from the Agent's **AI Providers** section. For native saved connections, select models inside Hermes or OpenClaw; see [Configure Cloud Agent AI access](/cloud-agents/ai-access). 1. Review the Agent name and status to confirm the target. 2. In **Language & timezone**, select the intended language and timezone. 3. Choose **Save changes** once, then wait for the update to finish. 4. Reopen Settings and confirm the saved values and final Agent status. Settings shows the intended values after reopening, and the Agent has finished its update before you resume work. Cloud Agent Settings with Language and timezone, Compute plan, Restart, Stop, and deletion controls. Cloud Agent Settings with Language and timezone, Compute plan, Restart, Stop, and deletion controls. *Settings scrolled to the runtime controls. Review the live subscription terms and confirmation before any paid or destructive action.* [Light full-size image](/assets/clawdi-demo-screenshots/light/agent-settings.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/agent-settings.webp) When you save a remote runtime change, the Agent can enter **Updating** while Clawdi applies it. During that transition: * An affected live tool can disconnect temporarily. * Save and lifecycle controls can be disabled. * Wait for the current operation to finish before submitting another change. * If Clawdi reports that the Agent state changed, refresh the page and review the latest settings before retrying. Compute plan changes also depend on the current Agent state, subscription state, and current offer availability. Use the enabled controls and exact quote shown in the product UI rather than assuming that a previously seen option is still available. ## Use lifecycle controls 1. Save your work outside any live Terminal or browser connection that could close. 2. Open **Settings > Agent controls** and choose the enabled action for the intended Agent. 3. Read any confirmation and submit once. Wait for the status to settle before retrying. 4. After starting or restarting, confirm **Running**, then open the Agent Interface and check that it has loaded. The Agent reaches the requested stable state: Running after a successful start or restart, or Stopped after a successful stop. | Action | When the dashboard enables it | Effect | | - | - | - | | **Start** | The Agent is **Stopped** or recoverable from **Failed**. | Begins startup of the remote runtime. | | **Stop** | The Agent is **Running** or **Starting**. | Pauses the remote runtime and makes its browser tools and Terminal unavailable until the next start. | | **Restart** | The Agent is **Running** or recoverable from **Failed**. | Restarts the whole Agent; expect live connections to close. | | **Delete** | The status is known, the Agent still exists, and deletion is not already underway. | Permanently removes the Agent and releases its remote resources. | The dashboard is authoritative for current-state constraints. If a button is disabled, do not try to reproduce the action through another surface. Wait for the active transition, choose **Check again**, or resolve the displayed failure first. Stopping a Cloud Agent is not deletion. It also does not by itself mean that a paid compute subscription has been cancelled. Manage compute funding from the Agent's Settings. ## Delete safely Deletion cannot be undone. Before confirming it: 1. Move any important remote work to source control or another external system. 2. Read the subscription choice in the confirmation dialog. When a renewable compute subscription is attached, the dashboard can ask whether to keep or cancel it. 3. Confirm both the Agent deletion and the intended subscription handling. 4. After deletion is accepted, allow the **Deleting** transition to finish instead of submitting another delete request. Deleting a Cloud Agent removes that Agent and its remote resources. Shared Clawdi objects keep their canonical meaning and are managed separately; do not use Agent deletion as a substitute for reviewing account-level Projects, Memories, Skills, Vaults, Connectors, Channels, or AI Providers. For a failed or unclear lifecycle action, follow [Cloud Agent states and recovery](/cloud-agents/states-and-recovery). # Cloud Agent states and recovery Source: https://docs.clawdi.ai/cloud-agents/states-and-recovery Interpret deployment state, distinguish it from tool readiness, and recover safely from failures. Use the status on the Cloud Agent's **Overview** as the source of truth for its remote runtime. A successful button click means Clawdi accepted an action; it does not mean every transition or tool is already complete. ## Lifecycle states | Status | What it means | Safe next step | | - | - | - | | **Starting** | Creation or startup is still in progress. | Wait for the status to change; do not submit a parallel deployment. | | **Running** | The remote runtime is running. | Use the Agent, then check each live tool's own readiness. | | **Stopping** | A stop request is in progress. | Let the transition finish before starting another lifecycle action. | | **Stopped** | The remote runtime is not running. | Choose **Start** when you need its tools again. | | **Restarting** | The whole Agent is restarting. | Expect the Agent Interface and Terminal to disconnect temporarily. | | **Updating** | A settings or compute change is being applied. | Wait for the current change before submitting another. | | **Failed** | Clawdi could not finish the most recent Agent action. | Read the failure panel and use only the remediation it offers. | | **Deleting** | Permanent deletion was accepted and cleanup is continuing. | Do not create another delete request. | | **Deleted** | The Agent and its remote resources have been removed. | Create a new Agent if you need a new remote runtime. | | **Status unavailable** | Clawdi cannot currently determine the lifecycle state. | Choose **Check again**; do not infer that the Agent is stopped or deleted. | ## Lifecycle readiness is not tool readiness `Running` describes the remote runtime. The **Agent Interface** published by the selected Agent software can still be preparing after that status appears. **Files** appears when file access is available for the Agent. The **Terminal** also establishes its own secure browser session and reports **Connecting**, **Connected**, or **Disconnected** independently. Use this order when checking readiness: 1. Confirm that the Cloud Agent status is **Running**. 2. Open **Hermes Dashboard** or **OpenClaw Control UI** and wait for the browser interface. If it is not ready yet, choose **Check again**. 3. Open **Files** when it is shown and you need to browse the Workspace. 4. Open **Terminal** when you need a shell. If its connection closes, choose **Reconnect** to start a new Terminal session. Some Agent details can appear after the runtime itself starts. A temporary missing-details message is not proof that deployment failed. ## Recover a transition safely 1. Refresh the Agent's Overview or choose **Check again** to obtain the latest status. 2. If the status is transitional, leave the current operation in place. A transition that takes longer than expected can still complete. 3. If the status is **Failed**, read the named failed action and its customer- safe reason. 4. Follow the action-specific remediation: * For a provider configuration failure, fix or replace the AI Provider, then save the Agent's AI settings. * For an insufficient Wallet balance, top up the Wallet, obtain a fresh quote where requested, and then retry. * A failed startup or restart can offer **Retry startup** or **Retry restart**. * A failed delete means the Agent was not deleted; review the reason before choosing **Retry delete**. 5. If the page says there is no safe one-click retry, do not repeat the action blindly. Review the current settings and contact support from the dashboard when the cause is still unclear. For an ambiguous CLI deployment, follow [Automate Cloud Agent deployment](/cloud-agents/deployment-automation) before retrying. For tool-specific recovery, continue to [Cloud Agent troubleshooting](/cloud-agents/troubleshooting). # Troubleshoot Cloud Agents Source: https://docs.clawdi.ai/cloud-agents/troubleshooting Resolve Cloud Agent deployment, readiness, live tool, settings, AI access, and billing problems. Start on the Cloud Agent's **Overview**. Record its current status and the name of the failed or in-progress action before retrying anything. ## Deployment ### Deploy a Cloud Agent is not shown The dashboard shows the Cloud Agent deployment path only when it can verify that the signed-in account currently has access. Refresh the page and sign in again. If the availability check still fails, use its retry action; do not use the Connected Agent flow as a substitute for a remote deployment. ### The CLI asks for authorization Use the browser authorization and version-specific help in [Automate Cloud Agent deployment](/cloud-agents/deployment-automation). A legacy manually entered API key does not authorize deployment. ### A CLI request timed out or lost its connection The request may already have been accepted. Keep the original request ID and choices, then follow [Recover an unclear outcome](/cloud-agents/deployment-automation#recover-an-unclear-outcome). ### Checkout or Agent details did not reopen Return to **Agents** and look for the accepted Cloud Agent. Use the payment ambiguity guidance in [Automate Cloud Agent deployment](/cloud-agents/deployment-automation#make-non-interactive-retries-idempotent). ## States and readiness ### Starting, Restarting, or Updating continues longer than expected The transition can still finish. Choose **Check again** and keep only the existing operation in progress. Do not stack lifecycle or settings actions. ### Status unavailable Clawdi cannot currently determine the state. Choose **Check again**. Do not infer that the Agent is stopped, safe to delete, or ready for another action. ### The Agent is Running but some details are missing The remote runtime and its projected Agent details can become available at different times. Retry the affected section. Available lifecycle actions and live tools can still work while the remaining details load. ## Agent Interface, Files, and Terminal ### Agent Interface is not ready Confirm the Agent is **Running**, then choose **Check again**. The selected Agent software can publish its browser interface after runtime readiness. Use Terminal while the interface starts when Terminal is available. ### A new Agent Interface window does not open Allow pop-ups for the Clawdi dashboard and try again. If access material cannot be loaded, open **Access** and retry there. Use **Reset access** only when you intend to rotate the current credentials or token and restart the Agent. ### Files is not shown or cannot be opened **Files** appears only when file access is available for that Cloud Agent. If it is absent, use Terminal or the Agent Interface. If the Files session cannot be authenticated, refresh the page and try again. If a new tab does not open, allow pop-ups for Clawdi and retry **Open in new window**. ### Terminal is disconnected Terminal requires a **Running** Agent. Start a stopped Agent, or wait for the current transition. Then choose **Reconnect** to request a new secure Terminal session. A prior browser shell session is not recovered as the same connection. ### A system command reports permission denied The Terminal uses the ordinary runtime user. Work in supported user and workspace locations. Do not depend on protected system paths, unrestricted package or service changes, or administrator privileges. ## Settings and lifecycle ### A lifecycle button is disabled The action is invalid for the current status or another action is still in progress. Wait for the transition or choose **Check again**. Use the enabled control shown for the latest state. ### A settings change failed Refresh the Agent and compare the current settings with the intended change. For a network or state conflict, confirm the latest status before retrying. If the failure panel says there is no safe one-click retry, do not repeat the mutation blindly. ### Deletion failed A failed delete means the Agent was not deleted. Review the displayed reason, then use **Retry delete** if offered. If deletion was accepted and the status is **Deleting**, wait for cleanup rather than submitting another request. ## AI access and models ### A saved provider is unavailable Open account-level **AI Providers** and check that the provider is still saved, ready, and compatible with the Agent software. Fix or replace it, then return to the Agent's **AI Providers** section and save the intended connection. Select a model there when required for Clawdi AI or a custom catalog; for a native saved connection, choose the model inside Hermes or OpenClaw. ### The Agent has no configured model access If **Configure inside agent** is selected, Clawdi intentionally sends no provider connection. Configure the provider inside the running Agent, or switch the Agent to Clawdi AI or a usable saved provider. ## Usage, Wallet, and compute ### Wallet balance is insufficient Open **Settings > Wallet**, review activity, and top up through the dashboard. Then request a fresh quote and retry the failed action. Do not reuse an expired quote. ### Stopping did not end a compute subscription That is expected: lifecycle and compute funding are separate. Open the Cloud Agent's **Settings > Compute plan** and use the subscription controls available for its current state. ### A charge is not on the Clawdi Usage page Clawdi **Usage** reports Clawdi AI spend for its displayed reporting window. Check **Wallet** for Wallet activity, **Compute** or the billing portal for remote compute charges, and the external provider for saved or in-Agent model usage. If the dashboard provides no safe remediation and the current state remains unclear, contact [Clawdi support](mailto:support@clawdi.ai) with the Agent name, current status, failed action, and customer-visible error message. Do not send provider secrets, access tokens, or Terminal output containing credentials. # Cloud Agent usage and billing Source: https://docs.clawdi.ai/cloud-agents/usage-and-billing Understand the durable boundaries between compute, Wallet, Clawdi AI usage, and external provider usage. Cloud Agent costs can come from two separate activities: running the remote compute and using a model service. Keep those boundaries separate when choosing a plan or investigating a charge. ## Check a charge 1. Open **Settings > Wallet** in the [Clawdi dashboard](https://cloud.clawdi.ai). The balance button in the top bar also opens Wallet. 2. Find the entry in **Transactions**. Check its type, funding source, status, amount, and date; use **Load more** for older activity. 3. For compute, open **Settings > Compute** or the Agent's **Settings > Compute plan** to review the subscription. For Clawdi AI model spend, open **Settings > AI Usage**. 4. Open the receipt or invoice when available. For an external AI Provider, review the provider's billing page. You can identify which activity caused the charge, how it was funded, and where to review its current subscription or usage details. Wallet settings and Transactions layout with financial and credential fields redacted. Wallet settings and Transactions layout with financial and credential fields redacted. *The demo Wallet illustrates where to review activity. Financial transaction fields, balances, payment details, and credential fields are redacted. Capture was read-only, with no payment action performed; review current amounts and offers in your own account.* [Light full-size image](/assets/clawdi-demo-screenshots/light/wallet.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/wallet.webp) ## Billing concepts | Surface | Scope | What it represents | | - | - | - | | **Compute** | Per Cloud Agent | Resources and funding for that Agent's remote runtime. | | **Wallet** | Account-wide | One balance used for Clawdi AI and for compute when Wallet funding is offered and selected. | | **Usage** | Account-wide reporting window | Clawdi AI spend and requests, including model and daily breakdowns when available. | | **Subscriptions** | Account-wide | Current compute subscriptions and the controls available for each one. | | **External AI Provider** | Provider account | Model usage made with a saved or in-Agent provider configuration. | | **Payment methods** | Account payment account | Saved payment methods available for supported card billing actions. | The **Usage** page reports Clawdi AI activity for its displayed reporting window. Wallet balance is not reset with that reporting window. For an external AI Provider, use that provider's own usage and billing surfaces as the source of truth. ## Review current compute offers Compute resources, prices, included capacity, billing terms, payment methods, and availability can change. For exact current information, use: * The **Compute** section of the Cloud Agent deployment wizard for a new Agent. * The **Compute plan** section in an existing Cloud Agent's **Settings**. * **Settings > Compute** in the dashboard for the account-wide **Your subscriptions** list. Use **Load more** when the list is longer than the first page. These product surfaces show the exact amount and confirmation before a paid action. This documentation intentionally does not reproduce a price or promise that a particular plan or payment method is available to every account. ## Understand a Compute trial Eligible accounts can receive a one-time trial on their first card-funded Basic or Performance subscription. New accounts use this trial offer rather than automatically receiving an ongoing free Basic allowance. Existing included Basic capacity remains shown as **Included**. * Read the trial duration, end date, subsequent price, and billing terms in the current checkout. Do not assume a trial is available because it was offered to another account. * Wallet-funded subscriptions do not include this card trial. Reusing a card to claim another trial is not supported. * Cancelling during the trial ends it immediately and stops the Agent; it does not keep running for the unused trial period. Review the confirmation before cancelling. * When checkout fails or expires, use the retry action shown. If payment status is unclear, check the existing subscription or contact support before starting a second checkout. A Compute trial covers the indicated Compute offer. Clawdi AI model usage continues to use Wallet funds separately. ## Use Wallet safely Open **Settings > Wallet** to review the current balance, top up, manage auto-reload when available, and inspect the unified **Transactions** history. Transactions can include Wallet and card-funded activity and link to a receipt or invoice when one is available. Use **Load more** for older entries. The [notification center](/account/notifications) shows account alerts such as low Wallet balance and automatic top-up problems. Open the relevant Wallet or subscription page to resolve the underlying issue. The top-up dialog shows the payment methods available for that transaction. Use only a method presented there; the set can change by account and payment context. When a paid compute action uses Wallet, confirm the exact debit and balance-after amount shown in its fresh quote. If the balance changes, a quote expires, or the product reports a shortfall, top up as needed and request a new quote. Do not confirm an old amount after the product asks for a fresh quote. ## Understand stop, delete, and subscriptions * **Stop** pauses the remote runtime; it does not itself cancel a paid compute subscription. * Compute plan controls live in each Cloud Agent's **Settings**. The unified **Settings > Compute** view lists subscriptions across Cloud Agents; available actions depend on current Agent and subscription state. * **Delete** permanently removes the Agent. When the deletion dialog offers a separate subscription choice, review it explicitly; do not assume Agent deletion always selects the desired subscription outcome. * A plan change can be immediate, scheduled, or still awaiting confirmation as shown in the dashboard. Do not submit a second plan change while the first is unresolved. For billing-related deployment failures, first check the Agent status and Wallet activity. Top up only through the dashboard, obtain a fresh quote, and then use the remediation presented by the failed action. See [Cloud Agent troubleshooting](/cloud-agents/troubleshooting#usage-wallet-and-compute). # Core concepts Source: https://docs.clawdi.ai/concepts/core-concepts Understand Clawdi's Agent model and the canonical objects shared across Agent workflows. Clawdi is one product and one shared layer around supported AI agents. The objects on this page keep the same meaning whether an Agent runs on your computer or remotely. ## Agent An **Agent** is the Clawdi object for an AI agent you add to your account. There are two ways to run and add one: | Run location | What it means | | - | - | | **Connected Agent** | The Agent runs on your computer and connects to Clawdi. You manage its local installation and runtime. | | **Cloud Agent** | The Agent runs remotely, and Clawdi manages its runtime and lifecycle. | This run-location choice is separate from **Agent software**. Claude Code, Codex, Hermes, OpenClaw, and other supported runtimes name the software the Agent uses; they do not name where it runs. Supported software and integrations can differ between the two run paths. ## Project A **Project** groups the Skills and Vault access an Agent or teammate can use. Link a Project to an Agent when that Agent should use its resources. Project sharing and access remain explicit. ## Memory A **Memory** is durable account-level context an Agent can recall, such as a preference, fact, or decision. Keep a Memory concise and reusable; do not use it for a complete transcript or secret value. ```bash theme={null} clawdi memory add "Use npm in this Project" clawdi memory search "package manager" ``` ## Session A **Session** is conversation history produced by an Agent. Clawdi stores or syncs supported Session data so you can review and recall earlier work. For Connected Agents, preview local synchronization before writing data: ```bash theme={null} clawdi push --dry-run clawdi pull --dry-run ``` ## Skill A **Skill** is reusable instruction content an Agent can read from a Project or its supported local Skill directory. For a Connected Agent, the Agent's guarded local filesystem remains authoritative for its local Skill files. Importing a Project Skill is an explicit action. Supported Cloud Agents can install Skills from public GitHub sources or reference Library Skills and receive their updates. See [Skills](/guides/skills) for each installation path. ```bash theme={null} clawdi skill install // --agent codex ``` ## Vault A **Vault** is an encrypted collection of keys that can be added to one or more Projects. Use a `clawdi://` reference instead of committing a plaintext value, then resolve the reference only for the command that needs it. ```bash theme={null} printf '%s\n' "$OPENAI_API_KEY" | clawdi vault set OPENAI_API_KEY --stdin clawdi run --env-file .env.clawdi -- npm run dev ``` Vault encryption is server-managed. The current service can decrypt stored Vault values and credential profiles; this release is not a zero-knowledge secret store. ## Connector A **Connector** links Clawdi to an app. After you connect an app in the [Clawdi dashboard](https://cloud.clawdi.ai), approved tools can be available to Agents through supported integrations such as MCP. Connector management is in the dashboard, not the CLI. ## Channel A **Channel** is a messaging connection between an external chat and a linked Agent. Some providers use a bot or account for that connection. Channel controls appear only for supported Agent workflows; use the availability shown in the dashboard or current CLI help. ## AI Provider An **AI Provider** records how an Agent reaches a model service, including provider configuration and a credential reference. It is distinct from the Agent software that uses it. For an Agent on your computer, the CLI maintains a local AI Provider catalog. The catalog stores metadata and credential references, not API key values, and model requests continue to go directly from the Agent runtime to the provider. For a Cloud Agent, the **AI Providers** and model controls in the Clawdi dashboard configure the remote runtime. The local catalog and the Cloud Agent controls are different surfaces for the same canonical concept; do not assume that a setting in one automatically changes the other. ```bash theme={null} clawdi ai-provider --help ``` ## Availability An object's definition does not change with Agent run location. The actions and integrations shown for an Agent can still vary by run path, Agent software, and current runtime state. Use the controls shown for that Agent and the `--help` output shipped with your CLI version. # Manage Connected Agent setup Source: https://docs.clawdi.ai/getting-started/connect-agents Connect supported Agent software, recover a lost connection, and manage local sync. Clawdi detects supported Agent software on your computer and lets you connect Claude Code, Codex, Hermes, OpenClaw, Pi, or OpenCode. Each selected installation keeps running locally and becomes a Connected Agent in Clawdi. ## Connect from the dashboard 1. In the [Clawdi dashboard](https://cloud.clawdi.ai), choose **New agent**, then **Connect your own agent**. The dialog opens on **Ask your agent**. 2. Copy the setup prompt from the dashboard into supported Agent software on that computer. Review the requested setup actions. 3. Complete browser authorization and follow the setup prompts. 4. Return to Clawdi and check that the connected Agent appears. Ask your agent setup tab with the registration prompt redacted and a waiting-for-connection state. Ask your agent setup tab with the registration prompt redacted and a waiting-for-connection state. *The setup dialog waits while you complete the connection on your computer. The account-specific registration prompt is redacted in this screenshot; copy your own current prompt from the [Clawdi dashboard](https://cloud.clawdi.ai).* [Light full-size image](/assets/clawdi-demo-screenshots/light/connected-ask-agent.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/connected-ask-agent.webp) Prefer to run the commands yourself? Follow the [Connected Agent quickstart](/getting-started/quickstart). Your computer needs to stay available for local work and syncing. ## Supported Agent software Agent software is a separate choice from where the Agent runs. | Agent software | Sessions | Skills | MCP setup | | - | - | - | - | | Claude Code | Supported | Supported | Automatic | | Codex | Supported | Supported | Automatic | | Hermes | Supported | Supported | Automatic | | OpenClaw | Supported | Supported | Manual guidance where required | | Pi | Supported | Not configured by Clawdi | Not configured by Clawdi | | OpenCode | Supported | Not configured by Clawdi | Not configured by Clawdi | Pi and OpenCode connect for Session sync only. Clawdi does not install its bundled Skill or configure MCP for these integrations. ## Detect and connect installed software Run the interactive setup: ```bash theme={null} clawdi setup ``` Clawdi checks the standard location for each supported option. Installed Agent software is selected by default; a data directory left by an older installation can appear without being selected. For the selected software, setup performs these user-visible actions: 1. Registers an Agent and this computer with Clawdi. 2. Adds the Clawdi MCP server where supported. 3. Installs the bundled `clawdi` Skill where supported. 4. Ensures the background sync daemon is installed and running. ## Select one software option Use `--agent` when automatic detection misses an installation or when you want to configure only one option. The flag identifies Agent software; it does not select the Agent's run location. ```bash theme={null} clawdi setup --agent codex ``` Accepted values are: ```text theme={null} claude_code codex hermes openclaw pi opencode ``` For non-interactive setup, `--yes` registers every detected option: ```bash theme={null} clawdi setup --yes ``` `--yes` selects every detected option. Use `--agent ` when you want to limit setup to one. ## Verify the connection ```bash theme={null} clawdi status clawdi doctor clawdi daemon status ``` If an Agent's MCP tools look stale, refresh its local wiring and restart the daemon: ```bash theme={null} clawdi setup --agent codex clawdi daemon restart ``` Replace `codex` with the matching value from the list above. ## Recover a lost connection If this computer was previously connected, restore its existing Agent instead of registering another one: ```bash theme={null} clawdi agent reconnect --agent codex clawdi daemon status ``` Select the intended existing Agent when prompted. If you already know its ID: ```bash theme={null} clawdi agent reconnect ``` Reconnecting can replace the Agent's connection to another computer. Review any takeover prompt before confirming. Signing out preserves local Agent registrations for a later sign-in to the same account; another account cannot reuse those registrations. Run `clawdi agent reconnect --help` for non-interactive and daemon options. ## Remove local integration To reverse setup for one Connected Agent: ```bash theme={null} clawdi teardown --agent codex ``` Use `clawdi teardown --help` to review the current options before removing more than one Agent's local integration. # Connect a local Agent Source: https://docs.clawdi.ai/getting-started/quickstart Install the Clawdi CLI and connect supported Agent software on your computer. This is the **Connected Agent** quickstart. Use it when Agent software already runs on your computer and needs access to that computer or its local tools. Most new users should start with the [Cloud Agent quickstart](/cloud-agents/deploy), which does not require a local installation. For a guided dashboard entry, follow [Ask your agent](/getting-started/connect-agents#connect-from-the-dashboard) and copy the current setup prompt from the [Clawdi dashboard](https://cloud.clawdi.ai) into your local Agent. Complete authorization yourself and verify the result. The manual steps below give you control over each stage. ## Before you begin * Review [System requirements](/installation/requirements). Native installers on macOS, Linux, and Windows do not require Node.js. For an npm-managed installation, install Node.js 24 or newer. * Install at least one [supported Agent software option](/getting-started/connect-agents#supported-agent-software) if you want `clawdi setup` to detect it automatically. ## Steps Run the installer as your normal user: ```bash theme={null} curl -fsSL https://clawdi.ai/install.sh | sh ``` Run without `sudo`. ```powershell theme={null} irm https://clawdi.ai/install.ps1 | iex ``` For a package-manager alternative, follow the [npm installation instructions](/installation#npm-installation), then continue with sign-in below. ```bash theme={null} clawdi auth login ``` Open the printed sign-in link, confirm the page shows the same code as the terminal, and approve. The CLI finishes automatically. On SSH or a headless machine, open the link on any device with a browser. See [Authentication](/account/authentication) for code expiry, interrupted sign-ins, and local credential safeguards. ```bash theme={null} clawdi setup ``` Select the detected Agent software you want to connect. Setup registers an Agent and starts background sync by default. It also adds the Clawdi MCP entry and bundled Skill where supported. Pi and OpenCode sync Sessions only; see the [support table](/getting-started/connect-agents#supported-agent-software). ```bash theme={null} clawdi doctor ``` A healthy setup reports successful checks for authentication, API reachability, registered Agents, Vault metadata, and Clawdi MCP. Agent software not installed on this computer can appear as unavailable without preventing an installed Agent from working. Your Connected Agent is ready. Open **Sessions** in the dashboard to check its synced history. For integrations with MCP setup, start a new Agent Session and ask what Clawdi tools are available. ## Next steps Select a specific Agent software option and verify its local integration. Understand the objects that stay consistent across Agent workflows. Follow task guides for Projects, Memories, Sessions, Skills, Vaults, Connectors, Channels, and AI Providers. Check for a release and update through the same installation owner. # What is Clawdi? Source: https://docs.clawdi.ai/getting-started/what-is-clawdi Learn how Clawdi gives AI agents one home for their context and tools. AI agents build up conversations, instructions, memories, credentials, and app connections. Clawdi brings the supported parts of that work into one product. **The best home for all your AI agents.** Run them in the cloud or connect your own—with their context and tools in one place. ## What Clawdi brings together Clawdi gives supported Agents a consistent way to work with: * **Sessions and Memories** for reviewing earlier work and keeping useful context available. * **Skills** for reusable instructions and **Vaults** for controlled access to secrets. * **Connectors and Channels** for working with apps and messaging services. * **Projects** for organizing resources and sharing access. * **AI Providers** for describing how an Agent reaches a model service. These objects belong to Clawdi, not to a separate product for each run location. Read [Core concepts](/concepts/core-concepts) for their precise definitions and availability notes. ## One product, two run paths New agent dialog with cloud deployment and local connection choices. New agent dialog with cloud deployment and local connection choices. *Choose where your Agent runs: on Clawdi or on your computer.* [Light full-size image](/assets/clawdi-demo-screenshots/light/new-agent-supported-types.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/new-agent-supported-types.webp) You can add an Agent to the same Clawdi account in either of these ways: | Run path | Where the Agent runs | Who manages the runtime | How to begin | | - | - | - | - | | **Cloud Agent** | Remotely | Clawdi | Create an Agent from the dashboard or deployment wizard | | **Connected Agent** | On your computer | You | Install the Clawdi CLI and connect supported Agent software | Connected Agent and Cloud Agent describe how an Agent runs and is added to Clawdi. They are not separate products. **Agent software**—the Agent implementation you use—is another choice and determines the Agent experience independently of its run path. You can start with either path and use both in one account. Choose per Agent instead of moving everything at once. For most new users, a Cloud Agent is the recommended starting point because it does not depend on an Agent installation or an always-available computer. Use a Connected Agent when the Agent needs direct access to your computer and its local tools. ## Why use Clawdi Clawdi is useful when you want to: * Find supported Agent activity and reusable context in one place. * Give an Agent selected Skills, secrets, and app connections without putting them directly in a project repository. * Keep using Agent software on your computer while adding a remote Agent for work that should not depend on that computer staying available. * Organize resources in Projects and share them intentionally. * Use the dashboard and CLI around the same Clawdi objects. The exact actions available can depend on the run path, Agent software, and current runtime state. Clawdi keeps the product model consistent even when a particular integration is not available everywhere. ## Choose your next step Follow the recommended path, deploy from the dashboard, and complete a first task. Connect Agent software that already runs on your computer. Choose an outcome guide for shared context, app access, Project sharing, or messaging. Read curated, user-facing Clawdi release notes. # AI Providers Source: https://docs.clawdi.ai/guides/ai-providers Connect model access for Cloud Agents and manage a separate local Provider Catalog. An AI Provider records how Agent software reaches a model service. Keep these two surfaces separate: | Surface | Scope | What it changes | | - | - | - | | Local Provider Catalog | One Connected Agent computer | Local records and credential references | | Dashboard AI Providers and Agent AI controls | Your remote account and selected Cloud Agent | Provider credentials and model access for the remote Agent | Changing one surface does not automatically change the other. See [Core concepts](/concepts/core-concepts#ai-provider) and [Cloud Agents](/cloud-agents/overview). ## Configure a Cloud Agent Provider Sign in to the [Clawdi dashboard](https://cloud.clawdi.ai). Keep provider credentials in the secure connection form and out of messages, screenshots, and Project instructions. 1. Open **Library > AI Providers** and choose **Add provider**. 2. Select a provider and, when offered, the matching region or plan. 3. Use the provider's credential link to obtain the correct API key, or complete the supported account sign-in flow. ChatGPT account access is offered only for compatible Agent software and connections. 4. Save the connection and resolve any readiness or connection-test warning. 5. Open the Cloud Agent's **AI Providers**, select the saved connection, and save the change. 6. Wait for the update to finish, then open Hermes or OpenClaw to choose a model and start a conversation. Cloud Agent AI Providers with Clawdi AI, Configure inside agent, and Add a provider. Cloud Agent AI Providers with Clawdi AI, Configure inside agent, and Add a provider. *Select AI access for this Cloud Agent after saving the account connection. Available providers and models depend on the runtime and account.* For supported native provider connections, Clawdi needs the credential; it applies it without requiring a model catalog or default model. The Agent software owns model selection, and connecting credentials preserves its existing model choices. Custom endpoints can still require an endpoint and model configuration. Clawdi AI uses its managed model catalog. Follow the fields shown for the chosen connection rather than applying native-provider instructions to every provider type. The saved connection is available to the intended Agent, and the Agent can start a conversation with a model supported by that connection. These controls update the remote runtime. They do not edit the local Provider Catalog on your computer. Conversely, `clawdi ai-provider add` does not assign a provider to a Cloud Agent. Removing a dashboard Provider that is assigned to a Cloud Agent can leave that Agent without model access. Reassign affected Agents first and review the impact shown by the removal confirmation. For local catalog, OAuth, import, export, and provider-specific options, use `clawdi ai-provider --help` and the relevant subcommand help. For remote lifecycle behavior, see [Cloud Agent settings and lifecycle](/cloud-agents/settings-and-lifecycle). ## Add a local Provider record Use an environment or exact Vault reference instead of putting an API key in the catalog: ```bash theme={null} clawdi ai-provider add openai-main \ --type openai \ --default-model \ --auth env:OPENAI_API_KEY clawdi ai-provider validate openai-main clawdi ai-provider test openai-main ``` The local catalog stores metadata and the `env:OPENAI_API_KEY` reference, not the environment variable's value. The default test checks configuration and credential availability. Add `--live` only when you intentionally want a direct provider probe. To use a Vault value, first copy the exact reference from `clawdi vault list` and pass it as the auth reference: ```bash theme={null} clawdi ai-provider add openai-vault \ --type openai \ --default-model \ --auth 'clawdi://project//vault/providers/field/OPENAI_API_KEY' ``` The local catalog lives on this computer. It does not upload its records to the dashboard AI Providers page, and Clawdi does not proxy the Agent's model requests; supported local Agent software calls the provider directly. ## Manage local records The released CLI manages Provider Catalog records; it does not activate or write provider configuration into a local Codex, Hermes, or OpenClaw installation. Inspect the shipped command list before automating a workflow: ```bash theme={null} clawdi ai-provider --help clawdi ai-provider list ``` Use the supported subcommands for the specific catalog task: ```bash theme={null} clawdi ai-provider edit openai-main --default-model clawdi ai-provider test openai-main clawdi ai-provider remove openai-main ``` The local catalog provides `list`, `add`, `edit`, `remove`, `validate`, `test`, `connect`, `complete-oauth`, `import-auth`, `export`, and `import`. Run the relevant subcommand with `--help` before using its credential or file options. Configure local Agent software through that software's supported settings; a catalog record by itself is inventory, not proof that an Agent is using it. # Talk to your Agent through Channels Source: https://docs.clawdi.ai/guides/channels Connect a bot, link it to an Agent, pair external chats, and remove only the relationship you intend. Use a Channel to talk to a Cloud Agent from Telegram, Discord, or WhatsApp. First link a bot to the Agent, then pair the chat you want to use. Choose a Cloud Agent with **Channels** in its sidebar. For the shortest walkthrough, follow [Connect a messaging Channel](/guides/workflows/connect-a-messaging-channel). ## Current provider availability The released dashboard supports Telegram and Discord bots and custom WhatsApp accounts. Use **Library > Channels** to see the providers and status currently shown for your account. Channels catalog with Clawdi Telegram, Telegram Topics, Discord, and WhatsApp Link Agent actions. Channels catalog with Clawdi Telegram, Telegram Topics, Discord, and WhatsApp Link Agent actions. *Open Channels to discover Clawdi bots or manage custom connections. Choose Link Agent for the bot you want to use.* ## Choose a Clawdi bot Open **Library > Channels** and review **Clawdi bots**. Choose **Link Agent** on the bot you want, select your Cloud Agent, then continue to pairing. A Clawdi bot lets you start without creating your own bot. ## Connect a bot Open **Library > Channels** in the [Clawdi dashboard](https://cloud.clawdi.ai), choose **Add channel**, and select a provider: * For Telegram, enter a name and the bot token obtained from BotFather. * For Discord, enter a name, bot token, application ID, and interactions public key from the Discord Developer Portal. * For WhatsApp, choose **Connect your account** and follow the linked-device setup. The dashboard adds the account under custom bots after the device connection completes. Submit once and wait for the Channel to appear under **Custom bots**. Bot tokens are secrets. Use the dashboard's credential field. For CLI automation, pass the name of an environment variable with `--provider-token-env`; do not place the token itself in shell history. Discord credentials are stored during setup but are not verified with Discord at creation time. Send a test message and check Channel activity and health before relying on it. Use a dedicated WhatsApp number, not your primary personal number. Replies from an Agent linked to the account are sent from that WhatsApp account. ## Link the Channel to an Agent Open the Agent's **Channels**, choose an available bot, and select **Link**. Check that the row now offers **Pair** and **Unlink**. A linked bot with zero paired chats is ready for the next step: authorizing your chosen chat. ## Pair WhatsApp Connecting a WhatsApp linked device does not link it to an Agent or pair a chat. Complete those separately: 1. Open the custom WhatsApp Channel and use **Link Agent** for the intended Cloud Agent. 2. From the linked Channel, choose **Pair chat** and follow the current QR, link, or pairing instructions. 3. Send a harmless test message and confirm the paired chat and Channel health. If the linked-device connection needs attention, open the WhatsApp Channel and use **Repair**. Finish the repair flow before changing Agent links or pairing another chat. ## Pair Telegram On the Agent's connected Channel row, choose **Pair**. Use one of the paths shown: * Scan the QR code or open the generated Telegram link for a direct chat. * For a group, add the bot and send the exact pairing command displayed by the dashboard. The pairing link and code expire. Generate a new one if the countdown ends before pairing completes. Pair Telegram sample dialog labeled SAMPLE — NOT FOR PAIRING, with pairing data redacted and a demonstration QR code. Pair Telegram sample dialog labeled SAMPLE — NOT FOR PAIRING, with pairing data redacted and a demonstration QR code. *SAMPLE — NOT FOR PAIRING. Pairing data is redacted, and the demonstration QR decodes to `https://example.com/clawdi-demo`. Generate a fresh pairing link in Clawdi for your own chat.* [Light full-size image](/assets/clawdi-demo-screenshots/light/channels-pair-sample.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/channels-pair-sample.webp) ## Pair Discord On the Discord connection, choose **Pair**, then select **Server** or **Direct message**: * For a server, add the bot with the generated install link. You need the provider permission stated by the dashboard. * In the target server or direct message, run `/clawdi_pair` and provide the generated code in its required `code` option. After pairing, the chat appears beneath the connected Channel on the Agent page. Check **Activity** and **Health** on the Channel page after a test message. ## Unpair one chat Use this when the bot and Agent should stay linked but one external chat should stop reaching it: * For Telegram, choose the unpair action beside the paired chat and confirm. * For Discord, run `/clawdi_unpair` inside the paired server or direct message. Other paired chats and the Channel link remain active. ## Unlink an Agent On the Agent's **Channels** section, choose the unlink action beside the bot and confirm. The Agent stops answering through that bot. The Channel remains available and can still be linked to other Agents. ## Remove the Channel Open the Channel detail page and choose **Remove** only when the bot connection itself should be retired. Removing a Channel stops linked Agents from sending and receiving through it and cannot be undone. Unpair a chat or unlink one Agent when that narrower action is sufficient. For CLI inspection and automation, start with: ```bash theme={null} clawdi channel list clawdi channel available clawdi channel links clawdi channel bindings clawdi channel --help ``` Avoid copying a full option table into scripts; provider fields and pairing outputs can vary by CLI version and account availability. # Connectors and MCP Source: https://docs.clawdi.ai/guides/connectors-and-mcp Connect an app in the dashboard and verify that supported Agents can reach Clawdi tools through MCP. Connect an app so your Agent can use its tools. Connections belong to your Clawdi account and are shared across Agents. Review the requested access before connecting an account. ## Connect an app Start in **Library > Connectors** in the [Clawdi dashboard](https://cloud.clawdi.ai): 1. Open **Library > Connectors** and search the current catalog. 2. Select an app and review **Available tools** before granting access. 3. If the detail page already shows **Ready**, no account is required. Skip to testing its tools. 4. Otherwise, choose **Connect Account** and complete the provider's consent flow or enter the credential fields shown. 5. Return to the Connector page and confirm that it shows **Connected**. The detail page shows **Connected** or **Ready** and lists the tools the Connector can expose. The dashboard catalog is the availability authority. Do not assume an app, authentication method, or tool is available because it appeared in an older list or another Clawdi installation. Shared Connectors catalog with Connect actions and Ready toolkits. Shared Connectors catalog with Connect actions and Ready toolkits. *Choose an app, then review its tools and connection status.* ## Try a small task Open your Agent and ask it to list its available tools for the app. Start with a harmless read, such as finding a test document, and review the result. A **Ready** toolkit may work without a connected account; account-based apps need their own authorization. ## Verify MCP for a Connected Agent `clawdi setup` registers the supported MCP entry for detected Agent software. Refresh one installation and verify the service endpoint: ```bash theme={null} clawdi setup --agent codex clawdi doctor ``` Replace `codex` with `claude_code`, `hermes`, or `openclaw`. Setup prints manual guidance if it cannot update that software's MCP configuration. A successful **Clawdi MCP** line in `doctor` means the endpoint is reachable; confirm the `clawdi` server in the Agent software's own MCP list as the final local check. Start a new Agent conversation and ask it to list its available Clawdi tools. The current tool list reflects native tools, active Connector accounts, and the caller's access. A Connector can be visible in the dashboard without being usable until its detail page reports **Connected** or **Ready**. `clawdi mcp` is the stdio server command registered for Agent software. A normal user does not need to keep it running in a separate terminal; the Agent starts it when needed. ## Check availability for a Cloud Agent Do not run local Connected Agent setup for a Cloud Agent. Open the Agent in the dashboard and use the Connector or integration controls shown for that remote runtime. If a capability or tool is absent, treat that UI and the Agent's live tool list as authoritative rather than assuming the local catalog applies. See [Cloud Agents](/cloud-agents/overview) for the run-path distinction and [Cloud Agent settings and lifecycle](/cloud-agents/settings-and-lifecycle) for its runtime controls. ## Disconnect an app Open the Connector detail page, find the connected account, and choose **Disconnect**. Confirm only after checking which Agent workflows use its tools. Disconnecting makes that account's approved tools unavailable immediately. Existing Agent conversations may still contain previously returned data. If tools are missing or stale, follow [MCP troubleshooting](/troubleshooting#mcp-tools-are-missing-or-stale). For current verification options, use `clawdi setup --help` and `clawdi doctor --help`. # Guides Source: https://docs.clawdi.ai/guides/index Follow practical Clawdi workflows for shared context, access, integrations, and model configuration. Start with a short workflow, then open the related capability guide when you need more options and safeguards. An Agent can run on your computer as a **Connected Agent** or remotely as a **Cloud Agent**; Agent software is a separate choice. Availability can vary by run path, Agent software, and current runtime state. Start with [Core concepts](/concepts/core-concepts) if Project, Memory, Session, Skill, Vault, Connector, Channel, or AI Provider is new to you. ## Everyday workflows Save one reusable preference and verify it in a new Agent interaction. Authorize an app and confirm its live tools before asking the Agent to act. Invite a Viewer, let them review access, and add the Project to an Agent. Connect a bot, link a Cloud Agent, pair one chat, and send a test message. ## Capability guides Organize Skills and Vault access, invite Viewers, and link Projects to Agents. Save durable context, search it, and update or remove outdated information. Sync, review, share, and export conversation history. Install Cloud Agent Skills and manage local files or reusable Library Skills. Store secrets, commit references, and resolve them only where needed. Connect apps and verify that an Agent can reach the available tools. Review a package's Skills and tools before installing it on a Cloud Agent. Connect a bot, link an Agent, and pair or unpair external chats. Keep the local Connected Agent catalog separate from Cloud Agent controls. For command discovery and version-specific flags, use [CLI commands](/cli/commands) and the `--help` output shipped with your installed CLI. # Remember useful facts and preferences Source: https://docs.clawdi.ai/guides/memories Save context your Agents can reuse, and keep it up to date. Memories help your Agents remember useful facts and preferences across conversations. They belong to your account and are available across your Agents. Sharing a Project leaves your Memories private to your account. ## Add and find Memories in the dashboard Open **Memories** in the [Clawdi dashboard](https://cloud.clawdi.ai): 1. Choose **Create memory**. 2. Enter concise content and select a category. 3. Save it, then use search or a category filter to find it again. Synthetic Memories organized by facts, preferences, patterns, decisions, and context Synthetic Memories organized by facts, preferences, patterns, decisions, and context *Concise records make durable context easier to review and recall over time.* Open a Memory to inspect its source, creation time, and recall count when that information is available. ## Check that your Agent can use it Start a new conversation with an Agent that has working Clawdi tools. Ask it to recall the preference you saved. Use one clear fact per Memory, such as: “For project updates, start with a short summary and the next actions.” Keep passwords and API keys in [Vaults](/guides/vaults-and-secrets). To remove outdated context, open the Memory and use its delete action. You can also ask your Agent to review and update a specific Memory. ## Write a useful Memory Keep one reusable fact, preference, pattern, decision, or piece of context in each Memory. Include the subject instead of relying on the current conversation. ```bash theme={null} clawdi memory search "pull request summaries" clawdi memory add "For pull requests, I prefer a short summary followed by verification results" --category preference clawdi memory search "pull request summaries" ``` Valid categories are `fact`, `preference`, `pattern`, `decision`, and `context`. If you omit `--category`, the CLI uses `fact`. The search returns the new Memory. A supported Agent with working Clawdi tools can recall it in later conversations. Never store passwords, API keys, private keys, tokens, or connection strings as Memories. Clawdi blocks likely secrets at this boundary; store them in a [Vault](/guides/vaults-and-secrets) instead. ## Extract Memories from a Session First make sure the supported Session is synced, then identify its local Session ID: ```bash theme={null} clawdi push --modules sessions --dry-run clawdi push --modules sessions clawdi session list --limit 10 clawdi session extract ``` Extraction asks the service's configured model to create Memories from that Session. Some deployments do not configure a memory-extraction model; in that case the CLI reports that extraction is unavailable and makes no Memories. Review extracted Memories in the dashboard and delete anything too broad, duplicated, sensitive, or no longer accurate. ## Update an existing Memory Use the full ID from JSON output to replace one Memory's content: ```bash theme={null} clawdi memory list --json clawdi memory update "For pull requests, include a brief summary and the checks that passed" --json ``` This changes the chosen record's content while keeping its category and source metadata. It does not create a new Memory if the ID is missing. Check the result before relying on it in a new Agent conversation. You can also ask an Agent with the appropriate Clawdi tools to review and update a specific Memory. Identify the exact record when several match, and keep secrets in Vaults. ## Delete outdated context The shortest path is the delete action on the Memory card or detail page. For the CLI, obtain the full ID from JSON output and remove that exact record: ```bash theme={null} clawdi memory list --json clawdi memory rm ``` Deletion removes the Memory from future recall. Use `memory update` when the same fact or preference has changed and you want to retain the existing record's context. Delete it when it should no longer be remembered. If an Agent cannot recall a known Memory, verify its Clawdi tools with [Connectors and MCP](/guides/connectors-and-mcp) and see the [MCP troubleshooting steps](/troubleshooting#mcp-tools-are-missing-or-stale). Run `clawdi memory --help` for the command surface shipped with your CLI. # Add tools with Plugins Source: https://docs.clawdi.ai/guides/plugins Browse a Cloud Agent's Plugins and review what a package adds before installing it. Plugins bundle reusable Skills and tool connections for a particular job. Start with the task you want your Agent to do, then choose a relevant package. ## Before you begin Open a **Running** Cloud Agent that has **Plugins** in its sidebar. Available packages depend on that Agent; the catalog shows the choices you can review. ## Find a Plugin 1. Open the Agent's **Plugins** section. 2. Browse the available packages. 3. Open a package to read its details. Cloud Agent Plugins catalog with package descriptions and Install actions. Cloud Agent Plugins catalog with package descriptions and Install actions. *Browse packages before deciding which tools your Agent needs.* ## Review and install 1. Check the publisher, version, and description. 2. Review the included **Skills** and **MCP servers**. MCP servers provide connections to tools and information the Agent can use. 3. Choose **Install** when you trust the package and need its capabilities. 4. Wait for the page to show the installation result. Resolve any displayed setup request or error before using the Plugin. Sui Development Plugin details with publisher, version, included Skills, MCP server, and Install action. Sui Development Plugin details with publisher, version, included Skills, MCP server, and Install action. *The detail page shows what the available package includes before installation.* [Light full-size image](/assets/clawdi-demo-screenshots/light/plugins-sui-detail.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/plugins-sui-detail.webp) These demo screens show available packages. Installation and a successful task are separate steps. After setup, try a small, low-risk task and review the result before granting access to sensitive work. Use [Skills](/guides/skills) for reusable instructions, or [Connect an app](/guides/workflows/connect-an-app) to connect an account you already use. # Organize and share a Project Source: https://docs.clawdi.ai/guides/projects-and-sharing Group reusable Skills and Vaults, then choose the people and Agents that can use them. A Project keeps related Skills and Vault access together. Use one for a team, client, or recurring workflow. ## Before you begin Sign in to the [Clawdi dashboard](https://cloud.clawdi.ai). Create a Custom Project for work you plan to share; Global and Agent Projects are personal working spaces with different sharing rules. Viewers can read Skills and key names and can retrieve the values of attached Vaults through runtime tools. Review Vault access before inviting someone. ## Start a Project 1. Open **Library > Projects** and choose **New Project**. 2. Name the Project and create it. 3. Open its **Skills** tab to add instructions, or **Vaults** to choose its secrets. The new Project appears in your Library, ready to link to an Agent. ## Use it with an Agent 1. Open the Agent's **Projects** section. 2. Find the Project and choose **Link**. 3. Open the linked Project to review the resources it makes available. Demo Project overview with Skills, Vaults, Agents, and Access tabs. Demo Project overview with Skills, Vaults, Agents, and Access tabs. *Open a linked Project to review its resources and the Agents that use it.* Choose **Unlink** when that Agent should stop using the Project. The Project stays in your Library. For Connected Agents, follow the explicit [Skill import steps](/guides/skills#import-a-project-skill-into-a-connected-agent) to copy Project Skills to that computer. ## Share with a teammate Open an owned Custom Project, choose **Access > Manage sharing**, enter the recipient's email, and choose **Invite**. The recipient signs in and accepts the invitation, then reviews the Project before linking it to their own Agent. Sharing gives Viewer access; the owner continues to manage the content. Follow [Share a Project](/guides/workflows/share-a-project) for a complete walkthrough. Review the advanced options below for share links and access removal. ## Create a Project In the dashboard, open **Library > Projects**, choose **New Project**, enter a name, and create it. The equivalent CLI path is: ```bash theme={null} clawdi project create "Engineering toolkit" --slug engineering clawdi project show engineering ``` Use a short, stable slug when you expect to reference the Project in commands. The Project appears under **Projects** and in `clawdi project list`. ## Add a Project to an Agent Open the Agent's **Projects** section, find the Project in the available catalog, and choose **Link**. Linked Projects remain visible in the same catalog; use **Unlink** to stop using one. The CLI equivalent is: ```bash theme={null} clawdi agent projects link --project engineering clawdi agent projects list ``` The Agent reads its fixed Agent Project first, followed by linked Projects in the displayed order. Linking a Project does not transfer ownership and does not turn it into the Agent's write target. To stop using it without changing Project membership: ```bash theme={null} clawdi agent projects unlink --project engineering ``` ## Invite a Viewer Open an owned Custom Project, choose **Access > Manage sharing**, enter the recipient's email, and choose **Invite**. Or run: ```bash theme={null} clawdi project invite engineering --email teammate@example.com ``` The recipient signs in, opens their inbox, and accepts the invitation: ```bash theme={null} clawdi inbox clawdi inbox accept # Or decline an invitation you do not want to accept. clawdi inbox decline clawdi project list --shared-with-me ``` Accepting grants Viewer membership. The recipient can inspect the Project before deciding whether to add it to an Agent. ## Share with a link Use a link when you want to send access yourself or the recipient may not have an account yet: ```bash theme={null} clawdi project share engineering --label "Contractor onboarding" ``` Copy the full URL immediately. Clawdi shows it only once; later listings retain the label and a recognizable prefix, not the complete token. The recipient can accept it in the share page or with: ```bash theme={null} clawdi inbox accept ``` If the CLI reports that a display name is required, set it in your dashboard profile and retry. ## Give an accepted Project to an Agent After reviewing the Project, the Viewer can link it from the Agent's **Projects** section or run: ```bash theme={null} clawdi agent projects link --project @owner-handle/engineering ``` Use the owner-qualified slug shown by `clawdi project list --shared-with-me` when an unqualified name could be ambiguous. ## Stop sharing Review the current people, invitations, and links first: ```bash theme={null} clawdi project members engineering clawdi project invites engineering clawdi project share-links engineering ``` Choose the action that matches the access you need to remove: ```bash theme={null} # Stop new accepts through one link; existing members keep access. clawdi project share-links engineering --revoke # Remove one accepted Viewer. clawdi project members engineering --remove teammate@example.com # Revoke all links, cancel pending invitations, and remove all Viewers. clawdi project unshare engineering ``` A Viewer can remove their own membership with: ```bash theme={null} clawdi project leave @owner-handle/engineering ``` Removing membership prevents that person's Agents from using the Project. It does not delete the owner's Project content. See [Skills](/guides/skills) for explicit Project Skill imports and [Vaults and secrets](/guides/vaults-and-secrets) for Vault attachment and reference rules. For current CLI variants, run `clawdi project --help`, `clawdi inbox --help`, and `clawdi agent projects --help`. # Find and share past conversations Source: https://docs.clawdi.ai/guides/sessions Review Agent Sessions, find a useful answer, and share only the conversation you choose. Sessions keep your Agent conversations available for review. Open an Agent's **Sessions** for its history, or **Console > Sessions** to look across Agents. Connected Agents upload history from their computer after setup; Cloud Agents show their history through Clawdi. ## Find a conversation 1. Open **Console > Sessions**. 2. Search for words from the conversation and narrow the results by Agent or activity. 3. Open a result to read the matching messages. 4. Within a Session, use search and the next/previous controls to find another match. Hermes Sessions list with synthetic conversation titles and dates. Hermes Sessions list with synthetic conversation titles and dates. *An Agent’s Sessions page keeps its conversation history together.* Search covers visible messages and summaries. Private reasoning and tool payloads are excluded. ## Share the useful part Open a Session and choose the smallest amount of content your recipient needs: * **Share** at the top: the current conversation. * **Share conversation to here** on a message: the conversation up to that point. * **Share response** on an Agent response: just that response. Create the link, then open it in a signed-out window to check what the recipient will see. New links are snapshots; later messages stay outside that snapshot. Anyone with an active link can read the shared content. Check for private information before sharing. Project membership and Session links are separate. ## Turn off access Open **Sessions > Shared Session links**, or the Session's **Share** dialog, to review and turn off active links. Older **Live** links can include later uploads, so review those too. Files someone already downloaded remain independent copies. ## Missing a conversation? For a Connected Agent, check that its computer is online and background sync is running. For a Cloud Agent, check the Agent's status in Clawdi. The advanced steps below cover sync checks and exporting a private copy. ## Sync a Connected Agent Session [Connected Agent setup](/getting-started/quickstart) installs the background daemon by default. Check it before doing a manual backfill: ```bash theme={null} clawdi daemon status clawdi session list --agent codex --project . ``` Preview the upload, then upload the Session metadata and content available to your CLI: ```bash theme={null} clawdi push --modules sessions --agent codex --project . --dry-run clawdi push --modules sessions --agent codex --project . ``` Replace `codex` with `claude_code`, `hermes`, `openclaw`, `pi`, or `opencode` when appropriate. Omitting `--project` uses the current directory for a normal `push`; use `clawdi push --help` before widening a backfill with `--all`. The command reports new, updated, or unchanged Sessions. They appear under **Sessions** in the dashboard and on the relevant Agent page. For a Cloud Agent, open that Agent's **Sessions** section or the global **Sessions** page. Do not run local `push` for a remote runtime; use the status shown on the Cloud Agent page. See [Cloud Agents](/cloud-agents/overview). ## Review and find a Session Open **Sessions** in the dashboard. Search visible user and assistant messages, summaries, folders, or Session IDs, then narrow results with Agent and activity filters. Results show matching context; opening a message match takes you to that message. Within a Session, use transcript search and its next/previous controls to move between highlighted matches. Read messages and Agent activity in chronological order or jump to the latest messages. Private reasoning and tool payloads are excluded from search. To find and read uploaded Sessions from the CLI: ```bash theme={null} clawdi session search "workspace setup" --agent codex --limit 10 clawdi session read clawdi session read --json ``` Use the Cloud Session ID returned by `search`. `session list` lists local Sessions; `search` and `read` use the uploaded Cloud copy. If a row exists but its messages do not, rerun the focused `push`. Metadata can arrive before a content upload succeeds, and the next push retries content that is not in sync. ## Mirror synced Sessions onto another computer For a Connected Agent installation on the destination computer: ```bash theme={null} clawdi pull --modules sessions --agent codex --dry-run clawdi pull --modules sessions --agent codex ``` `pull` writes a Clawdi-managed local mirror. It does not insert downloaded conversations into the Agent software's native Session history or make them resumable there. Use `clawdi config paths` to inspect the local paths for your installed CLI version instead of relying on a hard-coded directory. ## Share one Session Choose the smallest amount of conversation the recipient needs: | What to share | Action in the Session | | - | - | | The current conversation | Choose **Share** at the top of the Session. | | The conversation up to a message | Use that message's **Share conversation to here** action. | | One Agent response | Use the response's **Share response** action. | Create the link, copy it, and open it in a signed-out window to verify the intended content. Each new link is a snapshot: later messages are not added. Sharing includes visible conversation content, excluding private reasoning, system messages, and tool payloads. Anyone with an active link can read its shared content. Review visible messages for sensitive text, file paths, and quoted secrets before sharing. Session sharing is independent from Project sharing. ## Share from the CLI Read the uploaded Session before publishing a link: ```bash theme={null} clawdi session read --json clawdi session share ``` The second command asks for confirmation. For a deliberate non-interactive publication, add `--yes`. To limit the snapshot, use a message's `position` from the read output: ```bash theme={null} clawdi session share --through --yes --json clawdi session share --response --yes --json ``` Positions identify messages in the uploaded Session; do not substitute a row number counted in the browser. `--response` must select an Agent response. Use either `--through` or `--response`, or omit both for the current whole conversation. Review the returned link before sending it to anyone. Sharing requires account-level authorization. An Agent-bound or restricted key cannot create public links on the account's behalf. ## Review and turn off shared links Open **Sessions > Shared Session links** to review, copy, open, or turn off active links across Sessions. You can also manage a Session's links in its **Share** dialog. Older **Live** links can include later uploads. New **Snapshot** links retain only their chosen content. Turn off an older live link if you no longer want future uploads to be accessible through it; creating a snapshot does not turn off other links. From the CLI: ```bash theme={null} clawdi session shares --json clawdi session shares --page 1 --limit 25 --json clawdi session unshare --yes ``` Use the ID and `kind` from the listing. For an older live link, add `--legacy` and use that link's listed ID, not the original Session ID. Listing is paged; advance `--page` to review the remaining active links. ## Export as Markdown or JSON To export your uploaded Session without making it public: ```bash theme={null} clawdi session export > session.md clawdi session export --json > session.json ``` These commands write the export to standard output and do not create a share link. Review the local file before distributing it. For an existing public link, open its shared page and use **More options** to copy its Markdown or JSON URL. You can also append `.md` or `.json` to the exact share URL: ```text theme={null} https://cloud.clawdi.ai/s/.md https://cloud.clawdi.ai/s/.json ``` A snapshot link's share ID is distinct from the original Session ID. Copy the returned link rather than constructing it from a Session ID. Both formats respect the link's selected content and access state. Turning off a link cannot recall a file someone already downloaded or copied. Treat exports as independent copies. Run `clawdi session --help`, `clawdi push --help`, and `clawdi pull --help` for the filters available in your CLI version. See the [Clawdi CLI](/cli/index) for dry-run and JSON conventions. # Teach your Agent with Skills Source: https://docs.clawdi.ai/guides/skills Save reusable instructions in a Project and choose which Agents use them. A Skill saves instructions you want an Agent to reuse, such as how to prepare a meeting brief or review a document. ## Before you begin Choose a Project you own and decide what the Skill should help with. Keep passwords and API keys in [Vaults](/guides/vaults-and-secrets). ## Create a Project Skill 1. Open **Library > Projects** and select your Project. 2. Open **Skills**, then choose **Add skill**. 3. Enter a short name, a description, and the instructions. Choose **Add skill**. 4. Open the saved Skill and check its content. Project Skills tab with reusable demo instructions and the Add skill action. Project Skills tab with reusable demo instructions and the Add skill action. *Keep related instructions together in a Project.* Linked Cloud Agents receive updates to Project Skills. For a Connected Agent, import the Skill on its computer using the advanced steps below. Pi and OpenCode support Sessions syncing only. ## Review or copy a Skill Open a Skill to read its instructions and source Project. To make an independent copy, choose **Copy or move**, select a Project you own, and choose **Copy skill**. Choose **Move skill** only when you also want to remove it from the source Project. Later edits to the original leave that copy unchanged. Share the source [Project](/guides/projects-and-sharing) when people should use the same instructions. Project Skill detail showing its instructions, source Project, and Copy or move action. Project Skill detail showing its instructions, source Project, and Copy or move action. *Review the source before editing or copying instructions.* ## Install a Skill on a Cloud Agent 1. Open the Cloud Agent's **Skills** and choose **Install skill**. 2. Choose **Library** and select a Project Skill, or choose **GitHub** and provide the public repository and Skill path. 3. Review the instructions and supporting files, then install. 4. Wait for the Agent to report that the Skill is applied before trying it. A Library reference follows its source updates and requires continued access to that Project. Review GitHub Skills again when you choose to update them. Removing a Skill from one Agent leaves its Library source available. Built-in and read-only Skills stay managed by the Agent. Follow any readiness message on the page before retrying an unavailable installation. Skills guide what an Agent does. Review instructions and any included scripts before installing content from someone else. ## Manage a Cloud Agent's Skills from the CLI Remote commands take the Cloud Agent's ID. They do not use a local software name such as `codex`: ```bash theme={null} clawdi agent skills list --json clawdi agent skills read clawdi agent skills install --github owner/repository --path path/to/skill ``` Sign in with `clawdi auth login` for Cloud Agent management. To install a Library reference, obtain its full Skill ID from the Project inventory: ```bash theme={null} clawdi skill list --project engineering --json clawdi agent skills install --library clawdi agent skills list --json ``` Check the resulting status. Accepted installation or removal is still waiting for the Agent to apply it; failures and unavailable capabilities are reported rather than treated as completed work. After a GitHub operation's outcome is unclear, inspect the inventory first. To replay it, reuse the original `--request-id` and `--resource-version` printed by the command, together with the same source and target. A fresh install or removal uses the current state; do not reuse an old request ID for a different operation. Remove a managed Skill from the chosen Agent with: ```bash theme={null} clawdi agent skills rm ``` Review the source and target before installing or removing a Skill. Removing a reference does not delete the Library source. Use `clawdi agent skills --help` for the installed CLI's exact options. ## Create a Connected Agent Skill Scaffold a local Skill, edit its `SKILL.md`, then install the validated content into one Agent's authoritative Skill directory: ```bash theme={null} clawdi skill init my-skill clawdi skill add ./my-skill --agent codex ``` The Skill must declare `name` and `description` in its `SKILL.md` frontmatter. The command writes through the Agent adapter, then updates the Cloud inventory. If the projection upload fails after the local write, the daemon can retry it. To install a public GitHub Skill directly for an Agent: ```bash theme={null} clawdi skill install owner/repository/path/to/skill --agent codex ``` A Skill is executable guidance for an Agent. Review its `SKILL.md`, scripts, and referenced assets before installing content from a repository you do not control. ## Sync the Agent inventory Connected Agent setup starts background sync by default. For a focused manual check: ```bash theme={null} clawdi push --modules skills --agent codex --dry-run clawdi push --modules skills --agent codex ``` The expected result is a read-only Connected Agent Skill inventory in the dashboard. Edit these local files on the Agent's computer. Pi and OpenCode integrations sync Sessions only and do not support this Skill workflow. ## Create a Project Skill from the CLI Always name the destination explicitly so the command cannot choose an unexpected default: ```bash theme={null} clawdi skill add ./my-skill --project engineering clawdi skill install owner/repository/path/to/skill --project engineering clawdi skill list --project engineering ``` You must own the destination Project to mutate it. In the dashboard, open the Project and use **Add skill**; owners can also edit or remove its Cloud-owned Skills there. To copy a Project Skill in the dashboard, open **Library > Skills**, choose its source Project, select the Skill, then choose **Copy or move** and an owned destination. Choose **Copy skill** to keep the source, or **Move skill** to remove it from the source Project. The destination is independent: later source edits do not update it. Share the original Project when people should keep reading the same Skill. ## Import a Project Skill into a Connected Agent Linking a Project does not silently overwrite the Agent's local Skill files. Preview and perform an explicit import: ```bash theme={null} clawdi pull --modules skills --project @owner-handle/engineering --agent codex --dry-run clawdi pull --modules skills --project @owner-handle/engineering --agent codex ``` The source must be a Global or Custom Project; Agent Projects are rejected because their filesystems remain authoritative. A shared Project is a valid read source after you accept it. Rerun the explicit pull when you want to import later Project changes. The CLI reports the imported Skill and its local destination. Start a new Agent conversation if the Agent software only discovers Skills at startup. ## Remove the right copy Use the same explicit scope you used to create or install the Skill: ```bash theme={null} # Remove from this Agent's filesystem and update its projection. clawdi skill rm my-skill --agent codex # Remove only the Cloud-owned Project copy. clawdi skill rm my-skill --project engineering ``` Removing a Project copy does not remove independent copies in other Projects or an imported Agent copy. Removing an Agent copy does not delete the source Project Skill. Run `clawdi skill --help`, `clawdi push --help`, and `clawdi pull --help` for current source and target options. See [Projects and sharing](/guides/projects-and-sharing) before distributing a Project Skill. # Keep secrets in Vaults Source: https://docs.clawdi.ai/guides/vaults-and-secrets Store keys safely and choose which Projects can use them. Use a Vault for API keys and other private configuration your Agent needs. A Project can use a Vault you attach to it; an Agent gets access through its own workspace and linked Projects. ## Choose which Projects can use a Vault 1. Open your Project's **Vaults** tab. 2. Review the Vaults already in the Project. 3. Choose **Add** beside an available Vault, or **Create vault** for a new one. Project Vaults tab separating attached Vaults from available Vaults. Project Vaults tab separating attached Vaults from available Vaults. *Attach only the Vaults this Project needs.* Removing a Vault from a Project leaves its keys available to other attached Projects. Changing a shared Vault's contents affects every Project using it. ## Add a key in the dashboard 1. Open the Vault and choose **Add keys**. 2. Enter the key names and values in the private entry form. 3. Review the detected keys, then save. 4. Confirm that the saved key names appear in the Vault. Demo Vault with DEMO_ENVIRONMENT, DEMO_REGION, and DEMO_WORKSPACE and masked values. Demo Vault with DEMO_ENVIRONMENT, DEMO_REGION, and DEMO_WORKSPACE and masked values. *Saved key names remain visible. Values are write-only in this view.* [Light full-size image](/assets/clawdi-demo-screenshots/light/vault-populated.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/vault-populated.webp) Sharing a Project also gives its Viewers access to attached Vault values through runtime tools. Masked values in the dashboard still require careful access control. Review attachments before sharing. Clawdi manages Vault encryption and can decrypt stored values. Keep secrets out of conversations, screenshots, and committed files. The advanced steps below show how to use references when a command or configuration file needs a key. ## Store one secret safely Use a masked prompt for interactive entry and name the Project explicitly: ```bash theme={null} clawdi vault set providers/OPENAI_API_KEY --project engineering --prompt ``` For automation, `--stdin` avoids placing the value in a command-line flag: ```bash theme={null} printf '%s\n' "$OPENAI_API_KEY" | clawdi vault set providers/OPENAI_API_KEY --project engineering --stdin ``` The command creates the Vault if needed, stores the value, and prints an exact reference containing the Project ID. Copy that emitted reference instead of constructing one by hand. ## Import an existing dotenv file Review the source file, then import without `--yes` so the interactive summary and confirmation remain visible: ```bash theme={null} clawdi vault import .env.production --vault payments --section stripe --project engineering ``` The import reads valid dotenv identifiers, reports invalid identifiers it skips, and writes the accepted fields into one Vault section. Existing plaintext remains in the source file; remove or retain that file according to your own secret-handling policy after you verify the import. List names and copyable references without printing values: ```bash theme={null} clawdi vault list --project engineering ``` ## Commit references, not values Create a template such as `.env.clawdi` with the exact reference printed by `vault set`, `vault import`, or `vault list`: ```dotenv theme={null} STRIPE_SECRET_KEY=clawdi://project//vault/payments/section/stripe/field/STRIPE_SECRET_KEY ``` Exact references carry their Project scope and avoid ambiguous matches when an Agent has several linked Projects. Project-relative references remain useful for portable templates, but require an explicit Project, Agent, or linked folder context at resolution time. To link the current folder to a Project: ```bash theme={null} clawdi project folder link --project engineering clawdi project folder status ``` ## Run a command without writing plaintext Preview provenance first. Dry-run does not launch the child command or request plaintext values: ```bash theme={null} clawdi run --dry-run --env-file .env.clawdi -- npm run dev clawdi run --env-file .env.clawdi -- npm run dev ``` Only the child process receives the resolved environment. Prefer this path to `--all-vault-env`, which is a legacy broad-injection mode. ## Inject a file only when required Some tools require a physical configuration file. Preview, then write it: ```bash theme={null} clawdi inject --dry-run --in .env.clawdi --out .env.local clawdi inject --in .env.clawdi --out .env.local ``` The CLI creates the output with owner-only permissions and refuses to overwrite an existing file unless you pass `--force` explicitly. An injected file contains plaintext. Keep it out of version control, restrict access to it, and remove it when the consuming tool no longer needs it. Writing to stdout can also expose plaintext in terminal logs. ## Inspect one reference Use dry-run to verify its source without revealing the value: ```bash theme={null} clawdi read --dry-run ``` Run without `--dry-run` only when you intentionally need plaintext on stdout. Avoid `--json` in logs for non-dry-run secret commands. ## Reuse or detach a Vault Attaching makes one shared key set available through another Project: ```bash theme={null} clawdi vault attach payments --project client-app ``` A later write to that Vault changes the value for every attached Project. Detach one Project without deleting keys: ```bash theme={null} clawdi vault detach payments --project client-app ``` Deleting a key from a Vault attached to multiple Projects affects every one of them, so the CLI refuses the operation unless you confirm the global effect. Sharing a Project also gives its Viewers CLI runtime access to Vault values available through that Project. Review attachments before creating an invite or share link. See [Projects and sharing](/guides/projects-and-sharing). Run `clawdi vault --help`, `clawdi read --help`, `clawdi run --help`, and `clawdi inject --help` for version-specific scope and conflict options. # Connect a messaging Channel Source: https://docs.clawdi.ai/guides/workflows/connect-a-messaging-channel Connect a supported bot, link it to a Cloud Agent, and verify one paired chat. Use a Channel when people should reach a supported Cloud Agent from an external chat. Connecting a bot, linking it to an Agent, and pairing a chat are three separate relationships. ## Before you begin * Have a **Running** Cloud Agent. * In the dashboard, confirm that **Library > Channels** shows the messaging provider you want to use. * Choose a Clawdi bot, or prepare your own bot credentials for a custom connection. ## Steps Open **Library > Channels** in the [Clawdi dashboard](https://cloud.clawdi.ai). Choose a bot under **Clawdi bots**. To use your own, choose **Add channel** and complete the requested setup; it appears under **Custom bots**. For a custom WhatsApp account, use a dedicated number. Open the Cloud Agent's **Channels**, choose the bot, and select **Link**. The bot row now offers **Pair** and **Unlink**. Agent Channels with Clawdi Telegram linked, zero paired chats, and Pair and Unlink actions. Agent Channels with Clawdi Telegram linked, zero paired chats, and Pair and Unlink actions. *The bot is linked. Pair your chosen chat next.* [Light full-size image](/assets/clawdi-demo-screenshots/light/channels-linked-unpaired.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/channels-linked-unpaired.webp) Choose **Pair** and follow the current QR code, link, command, or code shown by the dashboard. If a pairing code expires, generate a new one instead of reusing it. Send a harmless message from the paired chat. Confirm that the chat appears beneath the linked Channel and review **Activity** and **Health** on the Channel page. The bot is linked to the intended Cloud Agent, the external chat is paired, and a test message appears in Channel activity without an error. Bot tokens are secrets. Enter them only in the dashboard credential field; never place them in a Memory, prompt, screenshot, or committed file. Provider setup, pairing details, unpairing, unlinking, removal, and CLI inspection are covered in the [Channels guide](/guides/channels). # Connect an app and verify its tools Source: https://docs.clawdi.ai/guides/workflows/connect-an-app Authorize an app in the dashboard and confirm the available tools from an Agent. A Connector links Clawdi to an app. Complete the connection in the dashboard, then verify the live tools before asking an Agent to use them. Code Interpreter ready with five tools and no account connection required Code Interpreter ready with five tools and no account connection required *Credential-free Connector toolkits can report Ready without external account authorization.* ## Before you begin * Sign in to the [Clawdi dashboard](https://cloud.clawdi.ai). * Have an Agent with a working Clawdi tool integration. * Have permission to authorize the app account you intend to connect. ## Steps Open **Library > Connectors**, select an app from the current catalog, and review its **Available tools**. The catalog is the source of truth for current app and authentication availability. If the Connector already shows **Ready**, continue to the next step. Otherwise, choose **Connect Account** and complete the consent or credential fields shown by the provider and dashboard. Return to the Connector detail page. Confirm that it shows **Connected** or **Ready** and still lists the tools you expect to use. Start a new Agent interaction and ask it to list the tools currently available for that app. Begin with a read-only request, and review the proposed action before allowing a tool to change external data. The Connector shows **Connected** or **Ready**, and the Agent's live tool list includes the app capability you intend to use. Tool availability can vary by Agent run path, Agent software, account access, and runtime state. For Connected Agent verification, disconnect behavior, and missing-tool recovery, use the canonical [Connectors and MCP guide](/guides/connectors-and-mcp). # Give an Agent shared context Source: https://docs.clawdi.ai/guides/workflows/give-an-agent-context Save one reusable preference and verify that an Agent can use it in a new interaction. Use a Memory when an Agent should remember a concise fact, preference, decision, or pattern across interactions. Memories are account-level context; they are not shared through Projects. ## Before you begin * Sign in to the [Clawdi dashboard](https://cloud.clawdi.ai). * Have a **Running** Cloud Agent whose Agent Interface can complete a basic interaction and whose live Clawdi tools include Memory access. * Choose non-secret context that will remain useful beyond one conversation. Agent Memories with Create memory, search, categories, and synthetic saved context. Agent Memories with Create memory, search, categories, and synthetic saved context. *Memories opened from an Agent still belong to the account. Provider configuration is optional; start with one useful Memory.* ## Steps Open **Memories**, choose **Create memory**, and write one self-contained preference. For example: “For project updates, use a short summary followed by the next actions.” Select the closest category and save it. Search Memories for a distinctive phrase from the preference. Confirm that the new Memory appears before testing it with an Agent. Open the Cloud Agent's **Hermes Dashboard** or **OpenClaw Control UI** and start a new interaction. Ask it to use your Clawdi context, for example: “Using my saved preferences, draft a project update for a launch that is on track.” Confirm that the response follows the saved preference. If the Agent does not use it, inspect the Agent's live Clawdi tools and follow the Memory troubleshooting links in the canonical guide. The Memory is searchable in the dashboard, and a new Agent interaction can use the preference without you repeating it in the prompt. Never store a password, token, private key, or connection string in a Memory. For categories, editing and deletion, CLI alternatives, and recall troubleshooting, use the canonical [Memories guide](/guides/memories). To share Project resources with another person instead, follow [Share a Project](/guides/workflows/share-a-project). # Share a Project with a teammate Source: https://docs.clawdi.ai/guides/workflows/share-a-project Invite a Viewer, let them review a Project, and add it to an Agent explicitly. Share a Custom Project when another person should be able to use its Skills and Vault access. Project membership and Agent linking are separate steps. ## Before you begin * Both people need Clawdi accounts. * Create or choose a **Custom Project**. Automatically created Global and Agent Projects cannot be shared. * Review every Vault attached to the Project before inviting anyone. A Viewer cannot edit the Project, but can read its Skills and key names and can resolve available Vault values through CLI runtime reads. Detach sensitive Vaults or use a separate Project before sharing. Project sharing dialog with an empty email field, Invite, People with access, and Create invite link. Project sharing dialog with an empty email field, Invite, People with access, and Create invite link. *Open Access, then Manage sharing. This demo has an empty invitation field and no active invite link.* [Light full-size image](/assets/clawdi-demo-screenshots/light/project-sharing.webp) · [Dark full-size image](/assets/clawdi-demo-screenshots/dark/project-sharing.webp) ## Steps In the [Clawdi dashboard](https://cloud.clawdi.ai), open **Library > Projects** and select the Custom Project you want to share. Open **Access > Manage sharing**, enter the teammate's email, and choose **Invite**. Review the recipient before sending. The teammate signs in, accepts the invitation from the top-right Notification Center, then opens the Project from their dashboard. They should review its Skills and Vault access before using it. The teammate opens the intended Agent's **Projects** section, finds the accepted Project, and chooses **Link**. Project membership and Agent access each require this explicit choice. The teammate can open the shared Project as a Viewer, and the Project appears in the selected Agent's linked Projects. For share links, CLI alternatives, member removal, and the exact effects of revoking access, use the canonical [Projects and sharing guide](/guides/projects-and-sharing). Review [Vaults and secrets](/guides/vaults-and-secrets) before adding secret access to a shared Project. # Start with Clawdi Source: https://docs.clawdi.ai/index The best home for all your AI agents. **The best home for all your AI agents.** Run them in the cloud or connect your own—with their context and tools in one place. A Cloud Agent runs remotely; a Connected Agent runs on your computer. Both run paths belong to one product. Clawdi Overview with demo Cloud Agents, Library resources, and recent Sessions. Clawdi Overview with demo Cloud Agents, Library resources, and recent Sessions. *Open an Agent from Overview, or use New agent to deploy or connect one.* **For most new users, a Cloud Agent is the best place to start.** Clawdi runs and manages it remotely, so there is nothing to install before your first task. Deploy from the Clawdi dashboard, wait for Running, and complete your first task in the Agent Interface. ## Run Agents locally or in the cloud **Cloud Agent** and **Connected Agent** describe where an Agent runs and who manages its runtime. Agent software is a separate choice: it determines the Agent experience, not the run path. You can use both run paths in the same Clawdi account. Already use Agent software on your computer? [Connect a local Agent](/getting-started/quickstart). This is the Connected Agent path and is the right choice when an Agent needs your computer or its local tools. ## Make your Agent useful After your first interaction, add only the context and access the Agent needs. Save one useful preference and confirm the Agent can use it in a new interaction. Authorize an app, check its status, and verify the live tool list before asking the Agent to act. Invite a teammate, let them review the Project, and add it to an Agent explicitly. Find practical workflows and detailed guidance for every shared Clawdi object. If you want the product model first, read [What is Clawdi?](/getting-started/what-is-clawdi). # Install the Clawdi CLI Source: https://docs.clawdi.ai/installation/index Install the Clawdi CLI with the native installer or npm and verify the executable. The Clawdi CLI connects Agent software on your computer and works with shared Clawdi objects. Installing the CLI does not create a Cloud Agent or install Agent software. Review the [system requirements](/installation/requirements) before you install. The native installer is the shortest path on macOS, Linux, and Windows, with no Node.js required. ## Native installation Run the installer as your normal user: ```bash theme={null} theme={null} theme={null} curl -fsSL https://clawdi.ai/install.sh | sh ``` Run without `sudo`. ```powershell theme={null} theme={null} theme={null} irm https://clawdi.ai/install.ps1 | iex ``` For a package-manager alternative, follow the [npm installation instructions](/installation#npm-installation), then continue with sign-in below. ```bash theme={null} theme={null} theme={null} clawdi auth login ``` Open the printed sign-in link, confirm the page shows the same code as the terminal, and approve. The CLI finishes automatically. On SSH or a headless machine, open the link on any device with a browser. See [Authentication](/account/authentication) for code expiry, interrupted sign-ins, and local credential safeguards. ```bash theme={null} theme={null} theme={null} clawdi setup ``` Select the detected Agent software you want to connect. Setup registers an Agent and starts background sync by default. It also adds the Clawdi MCP entry and bundled Skill where supported. Pi and OpenCode sync Sessions only; see the [support table](/getting-started/connect-agents#supported-agent-software). ```bash theme={null} theme={null} theme={null} clawdi doctor ``` A healthy setup reports successful checks for authentication, API reachability, registered Agents, Vault metadata, and Clawdi MCP. Agent software not installed on this computer can appear as unavailable without preventing an installed Agent from working. ### macOS and Linux The installer selects the release for your operating system and CPU, verifies the release artifact against its SHA-256 manifest entry, and installs under `~/.local` by default. If `~/.local/bin` is not on `PATH`, the installer adds it to your shell profile. Open a new terminal, or in bash or zsh run `export PATH="$HOME/.local/bin:$PATH"` to update the current shell. To skip updating your shell profile: ```bash theme={null} curl -fsSL https://clawdi.ai/install.sh | \ CLAWDI_NO_MODIFY_PATH=1 sh ``` To inspect the installer before running it: ```bash theme={null} curl -fsSL https://clawdi.ai/install.sh -o /tmp/clawdi-install.sh less /tmp/clawdi-install.sh sh /tmp/clawdi-install.sh ``` #### Choose a different prefix The prefix must be an absolute path that your user can write. The executable goes in `/bin` and versioned files go in `/share/clawdi`. ```bash theme={null} curl -fsSL https://clawdi.ai/install.sh | \ CLAWDI_INSTALL_PREFIX="/absolute/path" sh ``` ### Windows The PowerShell installer installs to `%USERPROFILE%\.local\share\clawdi\current` and adds that directory to your user `PATH`. It requires neither Node.js nor administrator access. Open a new terminal after installing. Use `clawdi update` to update in place. A native installation on CLI 0.15.8 or earlier cannot update itself; run the installer again once. To leave `PATH` unchanged, set the opt-out before running the installer: ```powershell theme={null} $env:CLAWDI_NO_MODIFY_PATH='1' irm https://clawdi.ai/install.ps1 | iex ``` The default release channel is `latest`. To select `beta`, set `$env:CLAWDI_CHANNEL='beta'` before running the installer. ## npm installation Install [Node.js 24 or newer](https://nodejs.org/), then use npm: ```bash theme={null} npm i -g clawdi ``` Use this alternative on macOS, Linux, or Windows when you prefer npm to own the installation. ## Verify the installation ```bash theme={null} clawdi --version clawdi --help ``` If the shell cannot find `clawdi`, open a new terminal and check the install directory is on `PATH`. ## Install an exact release Use an exact version when reproducing an environment or testing an upgrade. ```bash theme={null} CLAWDI_VERSION="X.Y.Z" curl -fsSL https://clawdi.ai/install.sh | \ CLAWDI_VERSION="$CLAWDI_VERSION" sh ``` ```powershell theme={null} $env:CLAWDI_VERSION='X.Y.Z'; irm https://clawdi.ai/install.ps1 | iex ``` ```bash theme={null} npm i -g clawdi@X.Y.Z ``` Replace `X.Y.Z` with a published semantic version. The native installer accepts the version without the release tag prefix. Find published versions on [GitHub Releases](https://github.com/Clawdi-AI/clawdi/releases) or [npm](https://www.npmjs.com/package/clawdi). ## Continue setup Follow [Connect a local Agent](/getting-started/quickstart) for the complete Connected Agent flow, or read [Authentication](/account/authentication) before you sign in. # System requirements Source: https://docs.clawdi.ai/installation/requirements Check supported operating systems, architectures, tools, and network access for the Clawdi CLI. Choose the native installer on supported macOS, Linux, and Windows computers, or npm on any platform that can run the required Node.js version. ## Supported installation paths | Platform | Native installer | npm installation | | - | - | - | | macOS x64 or arm64 | Supported | Supported with Node.js 24 or newer | | Linux x64 or arm64 | Supported for glibc and musl systems | Supported with Node.js 24 or newer | | Windows x64 or arm64 | Supported with PowerShell and `tar.exe` | Supported with Node.js 24 or newer | The native installer does not require Node.js. ## Native installer requirements The macOS and Linux installer requires: * A writable home directory, or an absolute writable path supplied through `CLAWDI_INSTALL_PREFIX`. * `curl`, `tar`, `gzip`, and `awk`. * Either `sha256sum` or `shasum` for release verification. * An x64 or arm64 CPU. Run the installer as the user who will use Clawdi. It rejects a `sudo` invocation that targets another user. The Windows installer requires PowerShell, an x64 or arm64 CPU, a writable user profile, and `tar.exe` (included in Windows 10 1803+ and Windows 11). Administrator access is not required. ## npm requirements The npm package requires: * Node.js 24 or newer. * npm and permission to write to npm's global package location. Confirm the versions before installation: ```bash theme={null} node --version npm --version ``` ## Network access Installation and normal use require outbound HTTPS access. The installer reads the current package release, downloads exact assets from GitHub Releases, and the CLI opens the Clawdi sign-in flow and connects to the Clawdi service. If a proxy or firewall blocks one of those steps, keep the complete error message but remove URLs containing credentials or private query parameters before sharing it with [Clawdi support](/support). ## Agent software The CLI can be installed without Agent software. To create a Connected Agent, install one of the [supported Agent software options](/getting-started/connect-agents#supported-agent-software) before running `clawdi setup`, or identify an existing installation with `clawdi setup --agent `. # Uninstall the Clawdi CLI Source: https://docs.clawdi.ai/installation/uninstall Remove Connected Agent integration, sign out, uninstall the CLI, and decide whether to retain local state. Uninstall in this order so the CLI can remove the integration it created. Removing the CLI is a local action. It does not delete your Clawdi account, server-side data, Project memberships, or Cloud Agents. Before uninstalling, record the current local paths while the CLI is still available: ```bash theme={null} clawdi config paths command -v clawdi ``` ```bash theme={null} clawdi daemon uninstall ``` This removes the per-user service unit and stops the local sync daemon. Review the registered Agent software, then remove all local registrations, bundled Skills, and supported MCP entries: ```bash theme={null} clawdi teardown --help clawdi teardown --all ``` Use `--agent ` instead of `--all` to remove only one Connected Agent integration. ```bash theme={null} clawdi auth logout ``` Sign-out removes the locally stored login and cached environment credentials. If `CLAWDI_AUTH_TOKEN` controls the current process, unset it separately. Confirm `command -v clawdi` points into `~/.local`, then remove the launcher and native release directory: ```bash theme={null} rm "$HOME/.local/bin/clawdi" rm -r "$HOME/.local/share/clawdi" ``` If you used `CLAWDI_INSTALL_PREFIX`, replace `~/.local` with that exact prefix. Do not remove a path until you have confirmed it belongs to the Clawdi native installer. ```bash theme={null} npm uninstall -g clawdi ``` ## Decide whether to keep local state Clawdi keeps local configuration, logs, and sync state under `~/.clawdi` by default. This directory remains after removing the executable unless you move or delete it explicitly. If you want a recoverable local cleanup, move the directory out of the way instead of deleting it immediately: ```bash theme={null} mv "$HOME/.clawdi" "$HOME/.clawdi.backup" ``` This local directory is separate from data stored in your Clawdi account. For an account or server-side data request, contact [Clawdi support](/support) and do not send credentials or Vault values. # Update the Clawdi CLI Source: https://docs.clawdi.ai/installation/update Check for Clawdi CLI releases, update through the current installation owner, and verify the result. The CLI can identify whether the current executable is owned by the native installer or a supported package manager and update through that same path. ## Check without installing ```bash theme={null} clawdi --version clawdi update --check ``` `--check` reports whether an update is available without changing the installation. ## Install the latest release ```bash theme={null} clawdi update clawdi --version clawdi doctor ``` For a native installation on macOS, Linux, or Windows, Clawdi downloads the exact release artifact, verifies its manifest checksum, and switches the stable launcher to the new version. For an npm-owned installation, it uses npm to install the exact version selected by the update check. Native installations on CLI **0.15.8 or earlier** cannot update themselves. Run the native installer from [Install the Clawdi CLI](/installation) once; later versions update normally. npm installations are unaffected. If Clawdi cannot identify the installation owner, it does not overwrite an unknown executable. Follow the exact manual command printed by the CLI, or reinstall through the path shown on [Install the Clawdi CLI](/installation). ## Control background updates Background update checks are enabled by default in the released CLI. Automatic updates install a release only after this computer has seen it as the latest version for at least 24 hours, and skip intermediate releases. `clawdi update` installs the latest release right away. To opt out of automatic updates while keeping manual `clawdi update` available: ```bash theme={null} clawdi config set autoUpdate false ``` Restore the default behavior: ```bash theme={null} clawdi config unset autoUpdate ``` For one process, set `CLAWDI_NO_AUTO_UPDATE=1` instead of changing stored configuration. ## Use an exact version To move to a specific published release, install that exact version through the same method you chose originally: ```bash theme={null} CLAWDI_VERSION="X.Y.Z" curl -fsSL https://clawdi.ai/install.sh | \ CLAWDI_VERSION="$CLAWDI_VERSION" sh ``` ```powershell theme={null} $env:CLAWDI_VERSION='X.Y.Z'; irm https://clawdi.ai/install.ps1 | iex ``` ```bash theme={null} npm i -g clawdi@X.Y.Z ``` Replace `X.Y.Z` with a published semantic version, then run `clawdi --version`. The built-in `--help` output is the command reference for the installed version. # Legacy Cloud Agents Source: https://docs.clawdi.ai/legacy-cloud-agents Read historical release notes for the Cloud Agent product generation that preceded the current experience. These notes cover Legacy Cloud Agents released before July 31, 2026. They are retained for historical reference, so product names, capabilities, and availability reflect the original release date. For current behavior, use the [Cloud Agents documentation](/cloud-agents/overview) and [Changelog](/changelog). ## Agent runtime and connected-chat upgrades This release updated Legacy Cloud Agents with newer OpenClaw and Hermes runtimes and more reliable chat connections. * New and existing Cloud Agents moved to OpenClaw 2026.5.19-beta.2 and Hermes 0.14.0 through the release's upgrade flow. * Telegram, Discord, WhatsApp, and iMessage connections were carried through the Agent upgrade more reliably. * Existing chat connections and custom bot settings were preserved more carefully. * Messaging and tool integrations loaded more consistently on new and upgraded Agents. ## OpenClaw and Instant Connect updates * Legacy Cloud Agents moved to OpenClaw 2026.5.7. * Agent pages showed connected Telegram, Discord, WhatsApp, and iMessage chats. * Users could disconnect a chat when they no longer wanted the Agent to reply there. * Pairing instructions became specific to each supported messaging service, and Discord showed the connected Channel. ## Hermes added as an Agent software choice * The dashboard added Hermes alongside OpenClaw as an Agent software option for Cloud Agents. * Channel setup brought the available messaging choices into one view. * The product site added a clearer comparison of the Agent software choices. ## Agent profiles and management tools * Agent Portraits added a public Agent profile with a shareable link. * Cloud Agents gained a Console for working with the Agent's terminal, files, and logs. * The dashboard added a place to browse Connectors and connect supported tools. * Messaging Channels could be assigned to individual Agents. * Reliability improved for long-running file operations. ## Skills, data services, and interface fixes * Newly created Cloud Agents included the Clawdi plugin without a separate setup step. * The release added Skills for searching news, browsing X posts, and checking Polymarket data. * Wide Markdown tables became scrollable instead of overflowing the chat view. * The Discord setup guide link was corrected. ## More reliable Cloud Agents * Cloud Agents recovered more reliably after service restarts. * Start, stop, restart, and delete actions behaved more consistently in the dashboard. * Checks that tell whether an Agent is ready and connected became more robust. ## More control over messaging bots * Users could configure their own Discord and Slack bots. * Switching between Clawdi-provided bots and user-provided bots became smoother. * The dashboard made Channel setup status and missing configuration clearer. ## Update running Agents from the dashboard * The dashboard added editing for key settings on a running Cloud Agent. * The configuration panel made Telegram and other messaging settings easier to adjust. * The update flow waited for the Agent to become available again before reporting completion. ## Easier MCP integration setup * Clawdi added Composio-backed MCP workflows. * The dashboard showed the connection details and token needed for a user's MCP setup. * Cloud Agent configuration handled more of the integration setup. ## The first public Clawdi foundation * Clawdi introduced its first public web experience with sign-in, a dashboard, and account management. * This release established the foundation for adding and managing Agents in Clawdi. # Self-host Clawdi Source: https://docs.clawdi.ai/self-hosting Operate Clawdi's shared open-source service as an advanced deployment choice. Most people can use Clawdi without running a backend, database, or dashboard. Self-hosting is for advanced users who want to operate the shared open-source service themselves. ## What self-hosting changes Self-hosting changes **who operates Clawdi's shared service**. It does not change the meaning of a Connected Agent or Cloud Agent, and it is independent of the Agent software you choose. The public open-source repository includes the CLI, backend, dashboard, database schema, and migrations. When you self-host the shared service, you take responsibility for its dependencies, authentication, encryption configuration, upgrades, and backups. Self-hosting the open-source service does not include the remote infrastructure that Clawdi runs for Cloud Agents. Do not use `clawdi deploy` as a way to add that infrastructure to a self-hosted service. ## Start from the public runbook Use the current public repository as the source of truth for prerequisites and local end-to-end setup: Review the current open-source setup instructions before operating the service yourself. After your backend is running, point the CLI at it before signing in. For Clerk OAuth, enable the device grant as described in [Self-hosted authentication](/account/authentication#self-hosted), then use `clawdi auth login`. If you already have an API key, use the manual fallback: ```bash theme={null} clawdi config set apiUrl http://localhost:8000 clawdi auth login --manual clawdi setup clawdi doctor ``` The localhost URL is for local setup. This user guide does not prescribe a production architecture; use the public repository's current self-hosting guidance for the release you operate. ## Decide whether to self-host * Use Clawdi without operating infrastructure when you want the shortest path to connecting Agents and working with shared objects. * Self-host when you need to inspect or change the open-source service and are prepared to operate its dependencies. * Choose where each Agent runs separately. To have Clawdi run an Agent remotely, start with [Cloud Agents](/cloud-agents/overview). # Clawdi support Source: https://docs.clawdi.ai/support Choose the right support channel and share diagnostics without exposing private data. Use email for account, private product, or billing questions. In the [Clawdi dashboard](https://cloud.clawdi.ai), you can also chat with support from **Help > Live chat**. Use Telegram for quick product questions that do not require sensitive diagnostics. Use a public GitHub issue for reproducible problems in the open-source CLI or repository when the report contains no private data. Contact [support@clawdi.ai](mailto:support@clawdi.ai) for help that should not be discussed in a public issue. Message @clawdiofficial for quick product questions. Do not send credentials, Vault values, or private diagnostics. Search or report a public CLI, self-hosting, or open-source product issue. ## Collect diagnostics Run read-only diagnostics first: ```bash theme={null} clawdi --version clawdi auth status clawdi status clawdi doctor clawdi daemon status ``` For a daemon problem, `clawdi daemon doctor --json` creates a broader snapshot for support handoff. Review and redact its output before attaching it. Include: * Your operating system and CPU architecture. * How the CLI was installed: native installer or npm. * The exact command that failed and its exit status. * The smallest reproducible sequence and what you expected. * Relevant output after applying the redaction checklist below. ## Redact before sending Remove or replace: * Access tokens, API keys, cookies, sign-in links and codes, bot tokens, and Vault values. * The contents of `~/.clawdi/auth.json`, `.env` files, credential profiles, and daemon token files. * Email addresses, user IDs, Agent IDs, Project IDs, Session IDs, Channel IDs, and private Project names. * Absolute file paths that reveal usernames or confidential directory names. * Session text, prompts, tool output, source code, and log lines unrelated to the failure. * URLs with query strings, user information, or non-public endpoints. Never run `clawdi read` to collect support diagnostics. It prints a resolved Vault value. Do not attach `auth.json` or send sign-in links or codes. Use placeholders such as ``, ``, ``, and `` while preserving the surrounding error text. ## Choose public or private support Use GitHub Issues when another user could reproduce the problem without your account, private content, or production details. Search existing issues first and include the installed CLI version. Use Telegram for quick product questions that do not require account details, private Agent state, or diagnostic attachments. Move the conversation to email before sharing information that should not remain in a chat. Use email when the problem involves an account, payment, private Agent state, or diagnostics that cannot be reduced to a safe public reproduction. Even in email, do not send credentials or secret values. # Troubleshoot Clawdi Source: https://docs.clawdi.ai/troubleshooting Diagnose Connected Agent sign-in, setup, Session sync, MCP, and daemon issues. For a remotely managed Agent, start with [Cloud Agent troubleshooting](/cloud-agents/troubleshooting). The checks below apply to the Clawdi CLI and Connected Agents on your computer. Start with the built-in diagnostic. It checks the current installation without resolving stored Vault secrets. ```bash theme={null} clawdi doctor ``` For a fuller snapshot, run: ```bash theme={null} clawdi --version clawdi auth status clawdi status clawdi daemon status ``` ## Sign-in does not complete Start a new sign-in: ```bash theme={null} clawdi auth login ``` Open the printed link on any device with a browser, confirm the page shows the same code as the terminal, and approve. This also works over SSH or on a headless computer. Keep the command running; it finishes automatically after approval. Codes expire after 10 minutes. If the code expired or you denied the request, run `clawdi auth login` again. If the command was interrupted while waiting, resume the same sign-in: ```bash theme={null} clawdi auth complete ``` If a self-hosted server reports that it does not allow device sign-in, ask its administrator to enable the Clerk OAuth application's device grant. See [Self-hosted authentication](/account/authentication#self-hosted). `clawdi auth login --manual` is for legacy Clawdi API keys and [self-hosting](/self-hosting). It does not authorize Cloud Agent deployment. ## No supported Agent software is detected First confirm the software is installed and its executable is on `PATH`. Then identify it explicitly: ```bash theme={null} clawdi setup --agent codex ``` Valid values are `claude_code`, `codex`, `hermes`, `openclaw`, `pi`, and `opencode`. Each value identifies Agent software. Pi and OpenCode support Session sync only; Clawdi leaves their Skills and MCP configuration untouched. See the [supported software table](/getting-started/connect-agents#supported-agent-software). ## MCP tools are missing or stale Refresh the selected Agent's setup, restart the daemon, and run the diagnostic again: ```bash theme={null} clawdi setup --agent codex clawdi daemon restart clawdi doctor ``` Use this MCP recovery path for Claude Code, Codex, Hermes, or OpenClaw, with the matching Agent software value. Review any manual guidance setup prints. For Pi or OpenCode, continue with the background Session sync checks below. ## Background sync is not running Inspect the service before reinstalling anything: ```bash theme={null} clawdi daemon status clawdi daemon doctor clawdi daemon logs ``` If setup was originally run with `--no-daemon`, install the daemon explicitly: ```bash theme={null} clawdi daemon install ``` ## Memory search returns no results Add a Memory, then search for a term it contains: ```bash theme={null} clawdi memory add "Use npm for this Project" clawdi memory search "npm" ``` ## Check for a CLI update ```bash theme={null} clawdi update --check ``` If an update is available: ```bash theme={null} clawdi update ``` Native installations update through native release assets. npm installations update through npm. ## Get more help Before reporting a problem, collect the output of `clawdi --version`, `clawdi doctor`, and the relevant command with `--help`. Follow the complete [diagnostic redaction checklist](/support#redact-before-sending) before sharing output. Choose email or a public issue and collect a safe diagnostic report. Review credential, Vault, third-party, and diagnostic boundaries. # Data and security Source: https://docs.clawdi.ai/trust/data-and-security Understand how Clawdi handles common data flows, credentials, Vault values, and support diagnostics. Use this page to understand where Clawdi runs, how credentials and Vault values move through common workflows, and what to review before sharing diagnostics. For governing terms, read the [Privacy Policy](https://www.clawdi.ai/privacy) and [Terms of Use](https://www.clawdi.ai/terms). ## Data location follows the run path For a **Connected Agent**, Agent software and its primary runtime remain on your computer. The CLI can upload Session and Skill data available to its sync commands, retrieve shared resources, and keep local integration state under `~/.clawdi` by default. For a **Cloud Agent**, the Agent runtime and the files managed through that runtime are remote. Connected Agent and Cloud Agent describe where the Agent runs; they do not change the meaning of shared Clawdi objects or make shared capabilities exclusive to one run path. Use dry-run modes before sync or secret-handling commands change anything: ```bash theme={null} clawdi push --dry-run clawdi pull --dry-run clawdi run --dry-run --env-file .env.clawdi -- npm run dev ``` ## Authentication data on your computer The CLI stores its normal login at `~/.clawdi/auth.json` and local configuration at `~/.clawdi/config.json`. `clawdi auth status` identifies the credential source without printing the token, but its output can include account identifiers and local paths. Protect the complete `~/.clawdi` directory, do not commit it, and never share `auth.json`, pending sign-in data, environment files, or daemon token files. ## Vault boundaries Vault values are stored server-side and resolved only for supported, authorized operations. Clawdi can decrypt stored Vault values and credential profiles; a Vault is not a zero-knowledge secret store. Prefer references and standard input over plaintext command-line flags: ```bash theme={null} printf '%s\n' "$OPENAI_API_KEY" | clawdi vault set OPENAI_API_KEY --stdin clawdi run --env-file .env.clawdi -- npm run dev ``` `clawdi read`, a non-dry-run `clawdi run`, and other resolving commands can place plaintext in a terminal or child process. Review command help and the destination process before resolving a value. Project sharing can authorize a recipient's supported CLI or Agent runtime to use shared Vault values even though the dashboard does not display plaintext. Read [Permissions and sharing](/account/permissions-and-sharing) before sharing a Project with an attached Vault. ## AI Providers and third parties For Connected Agents, the local AI Provider catalog stores metadata and credential references rather than API key values. Model requests continue from the Agent runtime to the selected provider. Connectors and Channels can send data to the external app or messaging service when an authorized Agent uses them. Review the terms and data practices of every model provider, Connector, and Channel you enable. Clawdi's permission to use a resource does not replace the external provider's controls. ## Diagnostics can contain private data Logs and JSON diagnostics can include emails, IDs, Project names, file paths, endpoint URLs, Session content, or tool output. Before sharing diagnostics: * Remove tokens, API keys, cookies, sign-in links and codes, and Vault values. * Remove `.env` contents and complete `clawdi://` references when their names or identifiers are sensitive. * Replace account, Agent, Project, Channel, and Session identifiers with placeholders. * Review every line rather than assuming `--json` output is anonymous. See [Clawdi support](/support) for a safe collection checklist. ## Policies and additional requirements Retention, deletion, backups, data residency, encryption guarantees, compliance, security assessments, incident response, and service levels are outside the scope of this product guide. Review the [Privacy Policy](https://www.clawdi.ai/privacy) and [Terms of Use](https://www.clawdi.ai/terms), and contact [Clawdi support](/support) about requirements that affect your use of the product.