设置

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（Node 22 LTS，目前为 22.14+，仍受支持）
pnpm
Docker（可选；仅用于容器化设置/e2e — 请参阅 Docker）

Tailoring strategy (so updates do not hurt)

如果您想要“100% 为我量身定制”并且轻松更新，请将您的自定义内容保留在：

Config: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
Workspace: ~/.openclaw/workspace (skills, prompts, memories; make it a private git repo)

Bootstrap once:

openclaw setup

From inside this repo, use the local CLI entry:

openclaw setup

If you don’t have a global install yet, run it via pnpm openclaw setup.

Run the Gateway(网关) from this repo

After pnpm build, you can run the packaged CLI directly:

node openclaw.mjs gateway --port 18789 --verbose

Stable workflow (macOS app first)

Install + launch OpenClaw.app (menu bar).
Complete the 新手引导/permissions checklist (TCC prompts).
Ensure Gateway(网关) is Local and running (the app manages it).
Link surfaces (example: WhatsApp):

openclaw channels login

Sanity check:

openclaw health

If 新手引导 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:

./scripts/restart-mac.sh

1) Start the dev Gateway(网关)

pnpm install
pnpm gateway:watch

gateway:watch runs the gateway in watch mode and reloads on relevant source, config, and bundled-plugin metadata changes.

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:

openclaw health

Common footguns

Wrong port: Gateway(网关) WS 默认为 ws://127.0.0.1:18789；请确保应用和 CLI 使用相同的端口。
Where state lives:
- 凭证：~/.openclaw/credentials/
- 会话：~/.openclaw/agents/<agentId>/sessions/
- 日志：/tmp/openclaw/

凭证存储映射

在调试认证或决定备份内容时请参考此表：

WhatsApp：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram bot token：config/env 或 channels.telegram.tokenFile（仅限常规文件；不接受符号链接）
Discord bot token：config/env 或 SecretRef（env/file/exec 提供者）
Slack tokens：config/env（channels.slack.*）
配对允许列表：
- ~/.openclaw/credentials/<channel>-allowFrom.json（默认账户）
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账户）
模型认证配置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
文件支持的机密负载（可选）：~/.openclaw/secrets.json
传统 OAuth 导入：~/.openclaw/credentials/oauth.json 更多详情：Security。

更新（不破坏您的设置）

将 ~/.openclaw/workspace 和 ~/.openclaw/ 视为“您自己的内容”；不要将个人的提示词/配置放入 openclaw 仓库中。
更新源代码：git pull + pnpm install（当锁定文件更改时）+ 继续使用 pnpm gateway:watch。

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户服务。默认情况下，systemd 会在注销/空闲时停止用户服务，这会终止 Gateway(网关)。新手引导会尝试为您启用 lingering（可能会提示输入 sudo）。如果仍然关闭，请运行：

sudo loginctl enable-linger $USER

对于常驻或多用户服务器，请考虑使用系统服务而不是用户服务（不需要 lingering）。有关 systemd 的说明，请参阅 Gateway(网关) runbook。