<!-- source: https://deepwiki.com/openclaw/openclaw/1.1-getting-started -->

# Getting Started

- docs/cli/update.md
- docs/gateway/security/index.md
- docs/gateway/security/shrinkwrap.md
- docs/install/development-channels.md
- docs/install/index.md
- docs/install/installer.md
- docs/install/updating.md
- docs/plugins/dependency-resolution.md
- docs/reference/release-performance-sweep.md
- extensions/acpx/package.json
- extensions/codex/package.json
- extensions/codex/src/app-server/request.ts
- extensions/codex/src/migration/apply.ts
- extensions/codex/src/migration/plan.ts
- extensions/codex/src/migration/provider.test.ts
- extensions/codex/src/migration/provider.ts
- extensions/codex/src/migration/source.ts
- extensions/tlon/package.json
- openclaw.mjs
- scripts/check-cli-startup-memory.mjs
- scripts/install-cli.sh
- scripts/install.ps1
- scripts/install.sh
- scripts/lib/plugin-npm-package-manifest.mjs
- scripts/write-cli-startup-metadata.ts
- src/cli/argv.test.ts
- src/cli/argv.ts
- src/cli/help-cold-imports.test.ts
- src/cli/plugins-install-record-commit.test.ts
- src/cli/root-help-metadata.ts
- src/cli/run-main-policy.ts
- src/cli/run-main.exit.test.ts
- src/cli/run-main.test.ts
- src/cli/run-main.ts
- src/cli/update-cli.test.ts
- src/cli/update-cli/update-command.ts
- src/commands/doctor-legacy-config.migrations.test.ts
- src/commands/doctor/shared/legacy-config-compatibility-base.ts
- src/commands/doctor/shared/legacy-config-core-normalizers.ts
- src/commands/migrate.test.ts
- src/commands/migrate.ts
- src/commands/migrate/output.test.ts
- src/commands/migrate/output.ts
- src/commands/migrate/selection.test.ts
- src/commands/migrate/selection.ts
- src/commands/migrate/skill-selection-prompt.test.ts
- src/commands/migrate/skill-selection-prompt.ts
- src/commands/migrate/types.ts
- src/commands/onboard-non-interactive.gateway.test.ts
- src/commands/onboard-non-interactive/config-write.ts
- src/commands/onboard-non-interactive/local.ts
- src/commands/onboard-non-interactive/remote.ts
- src/docs/clawhub-plugin-docs.test.ts
- src/entry.root-help-fast-path.test.ts
- src/entry.test.ts
- src/entry.ts
- src/infra/install-source-utils.test.ts
- src/infra/install-source-utils.ts
- src/infra/npm-install-env.test.ts
- src/infra/npm-install-env.ts
- src/infra/safe-package-install.test.ts
- src/infra/update-channels.test.ts
- src/infra/update-channels.ts
- src/infra/update-global.test.ts
- src/infra/update-global.ts
- src/infra/update-runner.test.ts
- src/infra/update-runner.ts
- src/plugins/provider-auth-choice.test.ts
- src/plugins/provider-auth-choice.ts
- src/scripts/test-live-media.test.ts
- src/wizard/setup.migration-import.ts
- src/wizard/setup.post-install-migration.test.ts
- src/wizard/setup.post-install-migration.ts
- src/wizard/setup.test.ts
- src/wizard/setup.ts
- test/openclaw-launcher.e2e.test.ts
- test/plugin-npm-package-manifest.test.ts
- test/scripts/check-cli-startup-memory.test.ts
- test/scripts/install-cli.test.ts
- test/scripts/install-ps1.test.ts
- test/scripts/install-sh.test.ts
- test/scripts/write-cli-startup-metadata.test.ts

OpenClaw is a personal AI assistant system that runs on your own hardware, serving as a multi-platform AI gateway between your messaging apps and AI agents. This page guides you through installing OpenClaw and performing your initial configuration using the onboarding wizard.

## Prerequisites

OpenClaw requires **Node.js 24 (recommended)** or **Node.js 22.19+** [scripts/install.sh19-22](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L19-L22) The system is designed to run on **macOS, Linux, and Windows**. The installer verifies the environment and ensures dependencies like `tar` and `curl`/`wget` are available for bootstrapping [scripts/install.sh59-71](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L59-L71) [scripts/install.sh189-193](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L189-L193)

On Linux, the installer handles non-interactive `apt-get` environments and ensures `DEBIAN_FRONTEND` is set correctly for repository configuration [test/scripts/install-sh.test.ts116-123](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/install-sh.test.ts#L116-L123) On Windows, the installer checks for a compatible `node.exe` and can automatically download a portable Node.js runtime if a system-wide installation is missing or outdated [scripts/install.ps1152-172](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.ps1#L152-L172) [scripts/install.ps1194-205](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.ps1#L194-L205)

**Sources:** [scripts/install.sh19-22](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L19-L22) [scripts/install.sh59-71](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L59-L71) [scripts/install.sh189-193](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L189-L193) [test/scripts/install-sh.test.ts116-123](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/install-sh.test.ts#L116-L123) [scripts/install.ps1152-172](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.ps1#L152-L172) [scripts/install.ps1194-205](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.ps1#L194-L205)

## Installation

The primary distribution method is via a shell installer (macOS/Linux) or PowerShell script (Windows). These scripts install the `openclaw` CLI, which serves as the entry point for all management tasks [scripts/install.sh265-275](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L265-L275)

### macOS and Linux

```

```

The `install.sh` script performs OS detection, bootstraps the `gum` UI tool for an interactive experience, and ensures a supported Node.js binary is active in the shell [scripts/install.sh136-153](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L136-L153) [scripts/install.sh168-187](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L168-L187) It specifically checks for Alpine Linux to use `apk` for Node.js installation before falling back to other methods [test/scripts/install-sh.test.ts157-168](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/install-sh.test.ts#L157-L168)

### Windows

```

```

The `install.ps1` script supports dry-run modes and specific install methods such as `npm` or `git` [scripts/install.ps15-13](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.ps1#L5-L13) It handles Windows-specific path issues by running command shims from a safe local directory via `Invoke-CommandFromWindowsSafeDirectory` [test/scripts/install-ps1.test.ts116-127](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/install-ps1.test.ts#L116-L127)

### Updating

OpenClaw features a robust update system implemented in `runGatewayUpdate` [src/infra/update-runner.ts12](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/update-runner.ts#L12-L12) It manages the entire lifecycle: fetching tags, checking out code (for git installs), running `pnpm build`, and performing post-update repairs via the `doctor` command [src/infra/update-runner.test.ts79-118](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/update-runner.test.ts#L79-L118)

```

```

The update command uses a "sentinel" file to track the health of the control plane during restarts, ensuring that a failed update can be diagnosed [src/cli/update-cli/update-command.ts70-76](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L70-L76)

**Sources:** [scripts/install.sh265-275](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L265-L275) [scripts/install.sh136-153](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L136-L153) [scripts/install.sh168-187](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L168-L187) [test/scripts/install-sh.test.ts157-168](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/install-sh.test.ts#L157-L168) [scripts/install.ps15-13](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.ps1#L5-L13) [test/scripts/install-ps1.test.ts116-127](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/install-ps1.test.ts#L116-L127) [src/infra/update-runner.ts12](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/update-runner.ts#L12-L12) [src/infra/update-runner.test.ts79-118](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/update-runner.test.ts#L79-L118) [src/cli/update-cli/update-command.ts70-76](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L70-L76)

## Onboarding Wizard

The recommended setup path is the onboarding flow, which is triggered automatically if no configuration is detected or via `openclaw onboard`.

### Onboarding Logic & CLI Entry

The CLI entry point `runCli` in `src/cli/run-main.ts` evaluates the environment to decide if the onboarding wizard (Crestodian) should start [src/cli/run-main.ts50-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.ts#L50-L57) If the configuration is missing or invalid, it routes the user to the setup wizard [src/cli/run-main.exit.test.ts54-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.exit.test.ts#L54-L57)

### Implementation & Data Flow

The wizard populates `openclaw.json`, the primary configuration file located at `CONFIG_PATH` [src/cli/update-cli/update-command.ts33](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L33-L33)

**Onboarding Logic Flow**

```

```

**Sources:** [src/cli/run-main.ts50-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.ts#L50-L57) [src/cli/run-main.exit.test.ts54-57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.exit.test.ts#L54-L57) [src/cli/update-cli/update-command.ts33](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L33-L33) [src/config/paths.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/paths.ts#L6-L6)

## Workspace & Plugin Configuration

OpenClaw uses a manifest-driven plugin architecture. During onboarding, plugins are synchronized based on the chosen update channel [src/cli/update-cli/update-command.ts97-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L97-L101)

### Plugin Management

The system tracks installed plugins using `PluginInstallRecord` objects [src/cli/update-cli/update-command.ts35](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L35-L35) When the system is updated or repaired, it runs `syncPluginsForUpdateChannel` to ensure all required plugins are present and compatible with the current version [src/cli/update-cli/update-command.ts97](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L97-L97)

### Model Providers

Onboarding involves configuring model providers (e.g., OpenAI, Anthropic). The system manages credentials via environment substitution to ensure secrets are handled securely [src/cli/update-cli/update-command.ts29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L29-L29)

**Plugin and Update Sequence**

```

```

**Sources:** [src/cli/update-cli/update-command.ts35](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L35-L35) [src/cli/update-cli/update-command.ts97-101](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L97-L101) [src/cli/update-cli/update-command.ts29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L29-L29) [src/infra/update-runner.ts12](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/update-runner.ts#L12-L12) [src/plugins/update.ts97](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/update.ts#L97-L97)

## System Health & Diagnostics

The `openclaw doctor` command is the primary tool for maintaining system health [src/cli/update-cli/update-command.ts16](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L16-L16)

### Doctor Capabilities

- Auto-Repair : Fixes common configuration issues and missing plugin dependencies src/infra/update-runner.test.ts 79-118
- Environment Validation : Ensures the Node.js version satisfies the engine requirements src/cli/update-cli/update-command.ts 57
- Shell Completion : Verifies and installs shell completion scripts src/cli/update-cli/update-command.ts 13-15

**Sources:** [src/cli/update-cli/update-command.ts16](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L16-L16) [src/infra/update-runner.test.ts79-118](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/update-runner.test.ts#L79-L118) [src/cli/update-cli/update-command.ts57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L57-L57) [src/cli/update-cli/update-command.ts13-15](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L13-L15)

## First Interaction

### 1. Verify Installation

Confirm the CLI is correctly installed and the version matches the expected release:

```

```

### 2. Start the Gateway

Run the gateway in the foreground to see initial logs and ensure the WebSocket server starts correctly:

```

```

The CLI uses a fast-path optimization for the `gateway run` command to minimize startup latency [src/cli/run-main.ts118-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.ts#L118-L158) This optimization, checked via `isGatewayRunFastPathArgv`, avoids heavy imports until it is certain the user wants to run the gateway [src/cli/run-main.ts160-183](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.ts#L160-L183)

### 3. Interactive Setup

If you skipped onboarding during installation, you can trigger it manually:

```

```

This will initialize your `openclaw.json` and prepare the workspace for agents [src/cli/update-cli/update-command.ts33](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L33-L33)

**Sources:** [src/cli/run-main.ts118-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.ts#L118-L158) [src/cli/run-main.ts160-183](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/run-main.ts#L160-L183) [src/cli/update-cli/update-command.ts33](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L33-L33)
