进阶设置

注意： 如果你是第一次配置，请从快速上手开始。向导的详细说明请参阅 Onboarding 向导。

最后更新：2026-01-01

太长不看

个性化配置都放在仓库外面： ~/.openclaw/workspace（工作区）+ ~/.openclaw/openclaw.json（配置文件）。
稳定工作流： 安装 macOS 应用，让它管理内置 Gateway。
前沿工作流： 自己通过 pnpm gateway:watch 运行 Gateway，然后让 macOS 应用以 Local 模式接入。

前置要求（从源码构建）

Node >=22
pnpm
Docker（可选，仅用于容器化部署或端到端测试 — 参见 Docker）

定制策略（让更新不翻车）

如果你想”100% 按自己的方式来”同时还要方便更新，把定制内容放在以下位置：

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

初始化一次：

openclaw setup

在本仓库内，使用本地 CLI 入口：

openclaw setup

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

从本仓库运行 Gateway

pnpm build 之后，可以直接运行打包后的 CLI：

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

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

安装并启动 OpenClaw.app（菜单栏）。
完成 onboarding 和权限清单（TCC 弹窗）。
确认 Gateway 为 Local 并正在运行（应用会自动管理）。
关联消息渠道（以 WhatsApp 为例）：

openclaw channels login

健全性检查：

openclaw health

如果你的版本中没有 onboarding 功能：

运行 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 中：

连接模式：Local 应用会接入配置端口上运行的 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：配置/环境变量或 channels.telegram.tokenFile（仅支持普通文件，不接受符号链接）
Discord bot token：配置/环境变量或 SecretRef（env/file/exec provider）
Slack token：配置/环境变量（channels.slack.*）
配对白名单：
- ~/.openclaw/credentials/<channel>-allowFrom.json（默认账户）
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账户）
模型认证 profile：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
基于文件的密钥载荷（可选）：~/.openclaw/secrets.json
旧版 OAuth 导入：~/.openclaw/credentials/oauth.json 更多详情：安全。

更新（不搞坏你的配置）

把 ~/.openclaw/workspace 和 ~/.openclaw/ 当作”你的东西”；不要把个人提示词和配置放进 openclaw 仓库。
更新源码：git pull + pnpm install（lockfile 变更时）+ 继续使用 pnpm gateway:watch。

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户服务。默认情况下，systemd 会在注销或空闲时停止用户服务，这会杀掉 Gateway。Onboarding 会尝试为你启用 lingering（可能会提示输入 sudo 密码）。如果仍未开启，手动运行：

sudo loginctl enable-linger $USER

对于需要持续运行或多用户的服务器，可以考虑使用系统级服务代替用户服务（无需 lingering）。详见 Gateway 运维手册中的 systemd 说明。