mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-10 04:00:44 +08:00
重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
This commit is contained in:
parent
4a23b715a2
commit
dbbe3add6a
14438 changed files with 2693620 additions and 2546 deletions
178
openclaw/docs/start/setup.md
Normal file
178
openclaw/docs/start/setup.md
Normal file
|
|
@ -0,0 +1,178 @@
|
|||
---
|
||||
summary: "Advanced setup and development workflows for OpenClaw"
|
||||
read_when:
|
||||
- Setting up a new machine
|
||||
- You want “latest + greatest” without breaking your personal setup
|
||||
title: "Setup"
|
||||
---
|
||||
|
||||
# Setup
|
||||
|
||||
<Note>
|
||||
If you are setting up for the first time, start with [Getting Started](/start/getting-started).
|
||||
For onboarding details, see [Onboarding (CLI)](/start/wizard).
|
||||
</Note>
|
||||
|
||||
## TL;DR
|
||||
|
||||
- **Tailoring lives outside the repo:** `~/.openclaw/workspace` (workspace) + `~/.openclaw/openclaw.json` (config).
|
||||
- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
|
||||
- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
|
||||
|
||||
## Prereqs (from source)
|
||||
|
||||
- Node 24 recommended (Node 22 LTS, currently `22.14+`, still supported)
|
||||
- `pnpm` preferred (or Bun if you intentionally use the [Bun workflow](/install/bun))
|
||||
- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))
|
||||
|
||||
## Tailoring strategy (so updates do not hurt)
|
||||
|
||||
If you want “100% tailored to me” _and_ easy updates, keep your customization in:
|
||||
|
||||
- **Config:** `~/.openclaw/openclaw.json` (JSON/JSON5-ish)
|
||||
- **Workspace:** `~/.openclaw/workspace` (skills, prompts, memories; make it a private git repo)
|
||||
|
||||
Bootstrap once:
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
From inside this repo, use the local CLI entry:
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
If you don’t have a global install yet, run it via `pnpm openclaw setup` (or `bun run openclaw setup` if you are using the Bun workflow).
|
||||
|
||||
## Run the Gateway from this repo
|
||||
|
||||
After `pnpm build`, you can run the packaged CLI directly:
|
||||
|
||||
```bash
|
||||
node openclaw.mjs gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
## Stable workflow (macOS app first)
|
||||
|
||||
1. Install + launch **OpenClaw.app** (menu bar).
|
||||
2. Complete the onboarding/permissions checklist (TCC prompts).
|
||||
3. Ensure Gateway is **Local** and running (the app manages it).
|
||||
4. Link surfaces (example: WhatsApp):
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
5. Sanity check:
|
||||
|
||||
```bash
|
||||
openclaw health
|
||||
```
|
||||
|
||||
If onboarding is not available in your build:
|
||||
|
||||
- Run `openclaw setup`, then `openclaw channels login`, then start the Gateway manually (`openclaw gateway`).
|
||||
|
||||
## Bleeding edge workflow (Gateway in a terminal)
|
||||
|
||||
Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
|
||||
|
||||
### 0) (Optional) Run the macOS app from source too
|
||||
|
||||
If you also want the macOS app on the bleeding edge:
|
||||
|
||||
```bash
|
||||
./scripts/restart-mac.sh
|
||||
```
|
||||
|
||||
### 1) Start the dev Gateway
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
# First run only (or after resetting local OpenClaw config/workspace)
|
||||
pnpm openclaw setup
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
`gateway:watch` runs the gateway in watch mode and reloads on relevant source,
|
||||
config, and bundled-plugin metadata changes.
|
||||
`pnpm openclaw setup` is the one-time local config/workspace initialization step for a fresh checkout.
|
||||
`pnpm gateway:watch` does not rebuild `dist/control-ui`, so rerun `pnpm ui:build` after `ui/` changes or use `pnpm ui:dev` while developing the Control UI.
|
||||
|
||||
If you are intentionally using the Bun workflow, the equivalent commands are:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
# First run only (or after resetting local OpenClaw config/workspace)
|
||||
bun run openclaw setup
|
||||
bun run gateway:watch
|
||||
```
|
||||
|
||||
### 2) Point the macOS app at your running Gateway
|
||||
|
||||
In **OpenClaw.app**:
|
||||
|
||||
- Connection Mode: **Local**
|
||||
The app will attach to the running gateway on the configured port.
|
||||
|
||||
### 3) Verify
|
||||
|
||||
- In-app Gateway status should read **“Using existing gateway …”**
|
||||
- Or via CLI:
|
||||
|
||||
```bash
|
||||
openclaw health
|
||||
```
|
||||
|
||||
### Common footguns
|
||||
|
||||
- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
|
||||
- **Where state lives:**
|
||||
- Channel/provider state: `~/.openclaw/credentials/`
|
||||
- Model auth profiles: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Sessions: `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Logs: `/tmp/openclaw/`
|
||||
|
||||
## Credential storage map
|
||||
|
||||
Use this when debugging auth or deciding what to back up:
|
||||
|
||||
- **WhatsApp**: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- **Telegram bot token**: config/env or `channels.telegram.tokenFile` (regular file only; symlinks rejected)
|
||||
- **Discord bot token**: config/env or SecretRef (env/file/exec providers)
|
||||
- **Slack tokens**: config/env (`channels.slack.*`)
|
||||
- **Pairing allowlists**:
|
||||
- `~/.openclaw/credentials/<channel>-allowFrom.json` (default account)
|
||||
- `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
|
||||
- **Model auth profiles**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- **File-backed secrets payload (optional)**: `~/.openclaw/secrets.json`
|
||||
- **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json`
|
||||
More detail: [Security](/gateway/security#credential-storage-map).
|
||||
|
||||
## Updating (without wrecking your setup)
|
||||
|
||||
- Keep `~/.openclaw/workspace` and `~/.openclaw/` as “your stuff”; don’t put personal prompts/config into the `openclaw` repo.
|
||||
- Updating source: `git pull` + your chosen package-manager install step (`pnpm install` by default; `bun install` for Bun workflow) + keep using the matching `gateway:watch` command.
|
||||
|
||||
## Linux (systemd user service)
|
||||
|
||||
Linux installs use a systemd **user** service. By default, systemd stops user
|
||||
services on logout/idle, which kills the Gateway. Onboarding attempts to enable
|
||||
lingering for you (may prompt for sudo). If it’s still off, run:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
For always-on or multi-user servers, consider a **system** service instead of a
|
||||
user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Gateway runbook](/gateway) (flags, supervision, ports)
|
||||
- [Gateway configuration](/gateway/configuration) (config schema + examples)
|
||||
- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
|
||||
- [OpenClaw assistant setup](/start/openclaw)
|
||||
- [macOS app](/platforms/macos) (gateway lifecycle)
|
||||
Loading…
Add table
Add a link
Reference in a new issue