docs(onboarding): add bootstrapping page (#9767)
Seb Slight
GitHub
parent
cf95b2f3f4
commit
3011b00d39
Binary file not shown.
|
After Width: | Height: | Size: 155 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 162 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 312 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 312 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 362 KiB |
|
|
@ -745,7 +745,7 @@
|
|||
"start/getting-started",
|
||||
{
|
||||
"group": "Onboarding",
|
||||
"pages": ["start/wizard", "start/onboarding"]
|
||||
"pages": ["start/wizard", "start/onboarding", "start/bootstrapping"]
|
||||
},
|
||||
"start/pairing"
|
||||
]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
|
||||
read_when:
|
||||
- Understanding what happens on the first agent run
|
||||
- Explaining where bootstrapping files live
|
||||
- Debugging onboarding identity setup
|
||||
title: "Agent Bootstrapping"
|
||||
sidebarTitle: "Bootstrapping"
|
||||
---
|
||||
|
||||
# Agent Bootstrapping
|
||||
|
||||
Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
|
||||
collects identity details. It happens after onboarding, when the agent starts
|
||||
for the first time.
|
||||
|
||||
## What bootstrapping does
|
||||
|
||||
On the first agent run, OpenClaw bootstraps the workspace (default
|
||||
`~/.openclaw/workspace`):
|
||||
|
||||
- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
|
||||
- Runs a short Q&A ritual (one question at a time).
|
||||
- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
|
||||
- Removes `BOOTSTRAP.md` when finished so it only runs once.
|
||||
|
||||
## Where it runs
|
||||
|
||||
Bootstrapping always runs on the **gateway host**. If the macOS app connects to
|
||||
a remote Gateway, the workspace and bootstrapping files live on that remote
|
||||
machine.
|
||||
|
||||
<Note>
|
||||
When the Gateway runs on another machine, edit workspace files on the gateway
|
||||
host (for example, `user@gateway-host:~/.openclaw/workspace`).
|
||||
</Note>
|
||||
|
||||
## Related docs
|
||||
|
||||
- macOS app onboarding: [Onboarding](/start/onboarding)
|
||||
- Workspace layout: [Agent workspace](/concepts/agent-workspace)
|
||||
|
|
@ -13,99 +13,67 @@ This doc describes the **current** first‑run onboarding flow. The goal is a
|
|||
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
|
||||
wizard, and let the agent bootstrap itself.
|
||||
|
||||
## Page order (current)
|
||||
|
||||
1. Welcome + security notice
|
||||
2. **Gateway selection** (Local / Remote / Configure later)
|
||||
3. **Auth (Anthropic OAuth)** — local only
|
||||
4. **Setup Wizard** (Gateway‑driven)
|
||||
5. **Permissions** (TCC prompts)
|
||||
6. **CLI** (optional)
|
||||
7. **Onboarding chat** (dedicated session)
|
||||
8. Ready
|
||||
|
||||
## 1) Welcome + security notice
|
||||
|
||||
Read the security notice displayed and decide accordingly.
|
||||
|
||||
## 2) Local vs Remote
|
||||
<Steps>
|
||||
<Step title="Approve macOS warning">
|
||||
<Frame>
|
||||
<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt=""></img>
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Approve find local networks">
|
||||
<Frame>
|
||||
<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt=""></img>
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Welcome and security notice">
|
||||
<Frame caption="Read the security notice displayed and decide accordingly">
|
||||
<img src="/assets/macos-onboarding/03-security-notice.png" alt=""></img>
|
||||
</Frame>
|
||||
</Step>
|
||||
<Step title="Local vs Remote">
|
||||
<Frame>
|
||||
<img src="/assets/macos-onboarding/04-choose-gateway.png" alt=""></img>
|
||||
</Frame>
|
||||
|
||||
Where does the **Gateway** run?
|
||||
|
||||
- **Local (this Mac):** onboarding can run OAuth flows and write credentials
|
||||
- **This Mac (Local only):** onboarding can run OAuth flows and write credentials
|
||||
locally.
|
||||
- **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;
|
||||
credentials must exist on the gateway host.
|
||||
- **Configure later:** skip setup and leave the app unconfigured.
|
||||
|
||||
Gateway auth tip:
|
||||
|
||||
<Tip>
|
||||
**Gateway auth tip:**
|
||||
- The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
|
||||
- If you disable auth, any local process can connect; use that only on fully trusted machines.
|
||||
- Use a **token** for multi‑machine access or non‑loopback binds.
|
||||
|
||||
## 3) Local-only auth (Anthropic OAuth)
|
||||
|
||||
The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:
|
||||
|
||||
- Opens the browser for OAuth (PKCE)
|
||||
- Asks the user to paste the `code#state` value
|
||||
- Writes credentials to `~/.openclaw/credentials/oauth.json`
|
||||
|
||||
Other providers (OpenAI, custom APIs) are configured via environment variables
|
||||
or config files for now.
|
||||
|
||||
## 4) Setup Wizard (Gateway‑driven)
|
||||
|
||||
The app can run the same setup wizard as the CLI. This keeps onboarding in sync
|
||||
with Gateway‑side behavior and avoids duplicating logic in SwiftUI.
|
||||
|
||||
## 5) Permissions
|
||||
</Tip>
|
||||
</Step>
|
||||
<Step title="Permissions">
|
||||
<Frame caption="Choose what permissions do you want to give OpenClaw">
|
||||
<img src="/assets/macos-onboarding/05-permissions.png" alt=""></img>
|
||||
</Frame>
|
||||
|
||||
Onboarding requests TCC permissions needed for:
|
||||
|
||||
- Automation (AppleScript)
|
||||
- Notifications
|
||||
- Accessibility
|
||||
- Screen Recording
|
||||
- Microphone / Speech Recognition
|
||||
- Automation (AppleScript)
|
||||
|
||||
## 6) CLI (optional)
|
||||
|
||||
The app can install the global `openclaw` CLI via npm/pnpm so terminal
|
||||
workflows and launchd tasks work out of the box.
|
||||
|
||||
## 7) Onboarding chat (dedicated session)
|
||||
|
||||
After setup, the app opens a dedicated onboarding chat session so the agent can
|
||||
introduce itself and guide next steps. This keeps first‑run guidance separate
|
||||
from your normal conversation.
|
||||
|
||||
## Agent bootstrap ritual
|
||||
|
||||
On the first agent run, OpenClaw bootstraps a workspace (default `~/.openclaw/workspace`):
|
||||
|
||||
- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`
|
||||
- Runs a short Q&A ritual (one question at a time)
|
||||
- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`
|
||||
- Removes `BOOTSTRAP.md` when finished so it only runs once
|
||||
|
||||
## Optional: Gmail hooks (manual)
|
||||
|
||||
Gmail Pub/Sub setup is currently a manual step. Use:
|
||||
|
||||
```bash
|
||||
openclaw webhooks gmail setup --account you@gmail.com
|
||||
```
|
||||
|
||||
See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.
|
||||
|
||||
## Remote mode notes
|
||||
|
||||
When the Gateway runs on another machine, credentials and workspace files live
|
||||
**on that host**. If you need OAuth in remote mode, create:
|
||||
|
||||
- `~/.openclaw/credentials/oauth.json`
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
|
||||
on the gateway host.
|
||||
- Microphone
|
||||
- Speech Recognition
|
||||
- Camera
|
||||
- Location
|
||||
</Step>
|
||||
<Step title="CLI">
|
||||
<Info>This step is optional</Info>
|
||||
The app can install the global `openclaw` CLI via npm/pnpm so terminal
|
||||
workflows and launchd tasks work out of the box.
|
||||
</Step>
|
||||
<Step title="Onboarding Chat (dedicated session)">
|
||||
After setup, the app opens a dedicated onboarding chat session so the agent can
|
||||
introduce itself and guide next steps. This keeps first‑run guidance separate
|
||||
from your normal conversation. See [Bootstrapping](/start/bootstrapping) for
|
||||
what happens on the gateway host during the first agent run.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
|
|
|||
Loading…
Reference in New Issue