1.4 初始设置 - OpenClaw中文社区

最后更新：2026-01-01

TL;DR

定制内容放在仓库外：~/.openclaw/workspace（工作区）+ ~/.openclaw/openclaw.json（配置）。
稳定工作流：安装 macOS 应用；让它运行内置的 Gateway。
前沿工作流：通过 pnpm gateway:watch 自己运行 Gateway，然后让 macOS 应用以本地模式连接。

前置条件（从源码）

Node ≥22
pnpm
Docker（可选；仅用于容器化设置/e2e — 见 Docker）

定制策略（让更新不那么痛苦）

如果你想"100% 为我定制"并且易于更新，请将你的自定义保存在：

配置：~/.openclaw/openclaw.json（JSON/JSON5 格式）
工作区：~/.openclaw/workspace（技能、提示词、记忆；建议做成私有 git 仓库）

一次性引导：

openclaw setup

从仓库内部使用本地 CLI 入口：

openclaw setup

如果还没有全局安装，通过 pnpm openclaw setup 运行。

稳定工作流（macOS 应用优先）

安装 + 启动 OpenClaw.app（菜单栏）。
完成引导/权限检查清单（TCC 提示）。
确保 Gateway 为本地并正在运行（应用会管理它）。
链接平台（示例：WhatsApp）：
```
openclaw channels login
```
健康检查：
```
openclaw health
```

如果你的版本中没有引导功能：运行 openclaw setup，然后 openclaw channels login，然后手动启动 Gateway（openclaw gateway）。

前沿工作流（终端中的 Gateway）

目标：开发 TypeScript Gateway，获得热重载，保持 macOS 应用 UI 连接。

0) （可选）也从源码运行 macOS 应用

如果你也想让 macOS 应用处于前沿：

./scripts/restart-mac.sh

1) 启动开发 Gateway

pnpm install
pnpm gateway:watch

gateway:watch 以 watch 模式运行 gateway，在 TypeScript 更改时重新加载。

2) 将 macOS 应用指向运行中的 Gateway

在 OpenClaw.app 中：

连接模式：本地 — 应用将连接到配置端口上运行的 gateway。

3) 验证

应用内 Gateway 状态应显示"Using existing gateway …"

或通过 CLI：

openclaw health

常见陷阱

端口错误：Gateway WS 默认为 ws://127.0.0.1:18789；保持应用 + CLI 在同一端口。
状态存储位置：
- 凭据：~/.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（尚不支持 token 文件）
Slack tokens	config/env（`channels.slack.*`）
配对白名单	`~/.openclaw/credentials/<channel>-allowFrom.json`
模型认证配置	`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
旧版 OAuth 导入	`~/.openclaw/credentials/oauth.json`

更多详情：安全。

更新（不破坏你的设置）

将 ~/.openclaw/workspace 和 ~/.openclaw/ 作为"你的内容"；不要将个人提示词/配置放入 openclaw 仓库。

更新源码：git pull + pnpm install（当 lockfile 更改时）+ 继续使用 pnpm gateway:watch。

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户服务。默认情况下，systemd 在登出/空闲时停止用户服务，这会杀死 Gateway。引导会尝试为你启用 lingering（可能会提示 sudo）。如果仍然关闭，运行：

sudo loginctl enable-linger $USER

对于永久在线或多用户服务器，考虑使用系统服务而非用户服务（不需要 lingering）。见 Gateway 运维手册的 systemd 注释。