mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-26 04:15:48 -06:00
Peter Steinberger
091f23ff49
* feat(cli): add openclaw triage for sanitized agent debugging handoffs Collects read-only doctor findings through a new collectDoctorFindings seam, reuses the sanitized diagnostics export, writes a bounded 8 KiB debugging prompt, and prints Claude Code / Codex / embedded agent handoff commands. Embedded --run gates on an interactive terminal plus a live inference probe. * fix(doctor): keep word separation when scrubbing multi-line errors scrubDoctorErrorMessage dropped newlines without substituting a space, so multi-line errors rendered with glued words in doctor and triage output. * feat(cli): hand triage prompts straight to a detected coding agent Interactive triage now detects installed agents via resolveExecutablePath, offers embedded/Claude Code/Codex/print in a picker, and spawns the chosen binary with the prompt, propagating its exit code. Embedded inference is probed only after selection. JSON output adds detectedAgents. * fix(cli): redact local paths in triage prompts and drop unlaunchable targets Prompt content now uses canonical path-aware redaction (redactSupportString), so paths reach external agents as ~/... or $OPENCLAW_STATE_DIR/... instead of absolute home paths; operator-facing JSON paths and printed commands stay real. Findings are fitted to the byte budget left after the trailing sections so the omission notice, bundle path, and privacy statement always survive truncation. Windows command shims are listed as manual commands rather than offered as a direct launch that shell-less spawn rejects. * fix(cli): clarify which Node runtime triage reports A live agent run flagged the reported version as wrong because the shell default differed from the runtime executing the CLI. * docs: route new installs to openclaw triage when setup fails Getting Started had no recovery path; add one that leads with triage, and document prompt location, environment inheritance, and exit codes on the CLI page. Keep the Triage page title untranslated like Doctor.
169 lines
5.0 KiB
Markdown
169 lines
5.0 KiB
Markdown
---
|
|
summary: "Get OpenClaw installed and run your first chat in minutes."
|
|
read_when:
|
|
- First time setup from zero
|
|
- You want the fastest path to a working chat
|
|
title: "Getting started"
|
|
---
|
|
|
|
Install OpenClaw, run onboarding, and chat with your AI assistant in about 5
|
|
minutes. By the end you will have a running Gateway, configured auth, and a
|
|
working chat session.
|
|
|
|
## What you need
|
|
|
|
- **Node.js 22.22.3+, 24.15+, or 25.9+** (Node 26 is the recommended runtime)
|
|
- **An API key** from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you
|
|
|
|
<Tip>
|
|
Check your Node version with `node --version`.
|
|
**Windows users:** the native Windows Hub app is the easiest desktop path. The
|
|
PowerShell installer and WSL2 Gateway paths are also supported. See [Windows](/platforms/windows).
|
|
Need to install Node? See [Node setup](/install/node).
|
|
</Tip>
|
|
|
|
## Quick setup
|
|
|
|
<Steps>
|
|
<Step title="Install OpenClaw">
|
|
<Tabs>
|
|
<Tab title="macOS / Linux">
|
|
```bash
|
|
curl -fsSL https://openclaw.ai/install.sh | bash
|
|
```
|
|
<img
|
|
src="/assets/install-script.svg"
|
|
alt="Install Script Process"
|
|
className="rounded-lg"
|
|
/>
|
|
</Tab>
|
|
<Tab title="Windows (PowerShell)">
|
|
```powershell
|
|
iwr -useb https://openclaw.ai/install.ps1 | iex
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
<Note>
|
|
Other install methods (Docker, Nix, npm): [Install](/install).
|
|
</Note>
|
|
|
|
</Step>
|
|
<Step title="Complete onboarding">
|
|
The installer starts the onboarding wizard automatically. Follow it to choose
|
|
a model provider, set an API key, and configure the Gateway. QuickStart is
|
|
usually only a few minutes, but provider sign-in, channel pairing, daemon
|
|
install, network downloads, skills, or optional plugins can make full
|
|
onboarding take longer. Skip optional steps and return later with
|
|
`openclaw configure`.
|
|
|
|
See [Onboarding (CLI)](/start/wizard) for the full reference.
|
|
|
|
</Step>
|
|
<Step title="Verify the Gateway is running">
|
|
```bash
|
|
openclaw gateway status
|
|
```
|
|
|
|
You should see the Gateway listening on port 18789.
|
|
|
|
</Step>
|
|
<Step title="Open the dashboard">
|
|
```bash
|
|
openclaw dashboard
|
|
```
|
|
|
|
This opens the Control UI in your browser. If it loads, everything is working.
|
|
|
|
</Step>
|
|
<Step title="Send your first message">
|
|
Type a message in the Control UI chat and you should get an AI reply.
|
|
|
|
Want to chat from your phone instead? The fastest channel to set up is
|
|
[Telegram](/channels/telegram) (just a bot token). See [Channels](/channels)
|
|
for all options.
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
<Accordion title="Advanced: mount a custom Control UI build">
|
|
If you maintain a localized or customized dashboard build, point
|
|
`gateway.controlUi.root` to a directory that contains your built static
|
|
assets and `index.html`.
|
|
|
|
```bash
|
|
mkdir -p "$HOME/.openclaw/control-ui-custom"
|
|
# Copy your built static files into that directory.
|
|
```
|
|
|
|
Then set:
|
|
|
|
```json
|
|
{
|
|
"gateway": {
|
|
"controlUi": {
|
|
"enabled": true,
|
|
"root": "${HOME}/.openclaw/control-ui-custom"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Restart the gateway and reopen the dashboard:
|
|
|
|
```bash
|
|
openclaw gateway restart
|
|
openclaw dashboard
|
|
```
|
|
|
|
</Accordion>
|
|
|
|
## If setup does not work
|
|
|
|
One command turns the current state of your install into a diagnosis you can act on:
|
|
|
|
```bash
|
|
openclaw triage
|
|
```
|
|
|
|
It runs read-only health checks, writes a sanitized prompt describing what it found, and then offers to hand that prompt to a coding agent it detects on your machine — Claude Code, Codex CLI, or the built-in OpenClaw agent — so the agent starts with the diagnosis already loaded. Pick "just print the commands" if you would rather run the handoff yourself.
|
|
|
|
Nothing leaves your machine until you choose an agent, and secrets, tokens, raw chat payloads, and raw logs are excluded from the prompt.
|
|
|
|
To read the findings yourself instead, run [`openclaw doctor`](/cli/doctor). For symptom-first routes, see [Troubleshooting](/help/troubleshooting).
|
|
|
|
## What to do next
|
|
|
|
<Columns>
|
|
<Card title="Connect a channel" href="/channels" icon="message-square">
|
|
Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more.
|
|
</Card>
|
|
<Card title="Pairing and safety" href="/channels/pairing" icon="shield">
|
|
Control who can message your agent.
|
|
</Card>
|
|
<Card title="Configure the Gateway" href="/gateway/configuration" icon="settings">
|
|
Models, tools, sandbox, and advanced settings.
|
|
</Card>
|
|
<Card title="Browse tools" href="/tools" icon="wrench">
|
|
Browser, exec, web search, skills, and plugins.
|
|
</Card>
|
|
</Columns>
|
|
|
|
<Accordion title="Advanced: environment variables">
|
|
If you run OpenClaw as a service account or want custom paths:
|
|
|
|
- `OPENCLAW_HOME` — home directory for internal path resolution
|
|
- `OPENCLAW_STATE_DIR` — override the state directory
|
|
- `OPENCLAW_CONFIG_PATH` — override the config file path
|
|
|
|
Full reference: [Environment variables](/help/environment).
|
|
</Accordion>
|
|
|
|
## Related
|
|
|
|
- [Install overview](/install)
|
|
- [Channels overview](/channels)
|
|
- [Setup](/start/setup)
|
|
- [Triage](/cli/triage)
|
|
- [Troubleshooting](/help/troubleshooting)
|