安装与开发环境配置（Setup）

首次安装？ 请先阅读 入门指南。 需要 onboarding 细节？参见 Onboarding（CLI）。

TL;DR

• 个人定制放在 repo 外： ~/.openclaw/workspace（工作区）+ ~/.openclaw/openclaw.json（配置）。
• 稳定工作流： 安装 macOS App，让它管理内置 Gateway。
• Bleeding Edge 工作流： 自己用 pnpm gateway:watch 跑 Gateway，然后让 macOS App 以 Local 模式连接。

前置要求（源码编译）

• Node 24 推荐（Node 22 LTS，目前 22.14+，仍受支持）
• pnpm
• Docker（可选；仅用于容器化环境/e2e 测试，参见 Docker）

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

如果你想"完全按自己来"又能轻松升级，请把定制内容放在：

• 配置： ~/.openclaw/openclaw.json（JSON/JSON5 格式）
• 工作区： ~/.openclaw/workspace（skills、prompts、memories；建议作为私有 git 仓库管理）

一次性初始化：

openclaw setup

在 repo 内使用本地 CLI 入口：

openclaw setup

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

从 repo 运行 Gateway

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

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

稳定工作流（以 macOS App 为主）

1. 安装并启动 OpenClaw.app（菜单栏）。
2. 完成 onboarding 和权限授权（TCC 弹窗）。
3. 确认 Gateway 处于 Local 模式并正在运行（App 自动管理）。
4. 连接频道（示例：WhatsApp）：

openclaw channels login

5. 健康检查：

openclaw health

如果你的构建版本没有 onboarding 界面：

• 运行 openclaw setup，然后 openclaw channels login，再手动启动 Gateway（openclaw gateway）。

Bleeding Edge 工作流（Terminal 运行 Gateway）

目标：在 TypeScript Gateway 上进行开发，实现热重载，同时保持 macOS App UI 连接。

0）（可选）从源码运行 macOS App

如果你也想让 macOS App 跑在最新代码上：

./scripts/restart-mac.sh

1）启动开发 Gateway

pnpm install
pnpm gateway:watch

gateway:watch 以 watch 模式运行 gateway，在相关源码、配置和内置插件元数据变更时自动重载。

2）把 macOS App 指向你运行的 Gateway

在 OpenClaw.app 中：

• Connection Mode 选 Local App 会自动连接到配置端口上正在运行的 gateway。

3）验证

• App 内 Gateway 状态应显示 "Using existing gateway …"
• 或通过 CLI 验证：

openclaw health

常见坑

• 端口错误： Gateway WS 默认 ws://127.0.0.1:18789；App 和 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 提供商）
• Slack tokens：配置/环境变量（channels.slack.*）
• 配对许可名单：
  • ~/.openclaw/credentials/<channel>-allowFrom.json（默认账号）
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账号）
• 模型认证配置： ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 文件型 secrets payload（可选）： ~/.openclaw/secrets.json
• 旧版 OAuth 导入： ~/.openclaw/credentials/oauth.json 详细说明：安全性文档

更新（不破坏现有配置）

• 把 ~/.openclaw/workspace 和 ~/.openclaw/ 当作"你自己的东西"；不要把个人 prompts/配置放进 openclaw repo。
• 更新源码：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 说明。

相关文档

• Gateway 运维手册（标志、监督、端口）
• Gateway 配置（配置 schema + 示例）
• Discord 和 Telegram（回复标签 + replyToMode 设置）
• OpenClaw 助手设置