OpenClaw 提供两种开发工作流：稳定版通过 macOS App 管理内置 Gateway，Bleeding Edge 通过终端运行 pnpm gateway:watch 实现源码热重载。关键配置存储于 ~/.openclaw/，首次运行需执行 openclaw setup 初始化；Gateway WS 默认端口 18789，Linux 下需要执行 sudo loginctl enable-linger $USER 防止 systemd 用户服务因登出而关闭。Node 24 推荐，pnpm 为必需依赖。

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

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

TL;DR

根据你想要的更新频率和是否自己运行 Gateway，选择对应工作流：

• 个人定制放在 repo 外： 将配置和工作区放在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace/，这样仓库更新不会影响它们。
• 稳定工作流（推荐多数用户）： 安装 macOS App，让它管理内置 Gateway。
• Bleeding Edge 工作流（开发者）： 自己通过 pnpm gateway:watch 运行 Gateway，然后让 macOS App 以 Local 模式连接。

前置要求（源码编译）

• Node 24 推荐（Node 22 LTS，当前 22.19+，仍受支持）
• pnpm 必需（源码检出需要）。OpenClaw 开发模式下从 extensions/* pnpm workspace 包加载内置插件，根目录 npm install 无法准备完整源码树。
• Docker（可选；仅用于容器化环境/e2e 测试，参见 Docker）

定制策略：让更新不破坏配置

如果你想“完全按自己来”又能轻松升级，请将定制内容保存在：

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

一次性初始化：

openclaw setup

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

openclaw setup

如果尚未全局安装，可用 pnpm openclaw setup 运行。

从仓库运行 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 工作流：终端运行 Gateway

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

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

如果你想保持 macOS App 也使用最新代码：

./scripts/restart-mac.sh

1）启动开发 Gateway

pnpm install
# 首次运行或重置本地 OpenClaw 配置/工作区后执行
pnpm openclaw setup
pnpm gateway:watch

gateway:watch 启动或重启 Gateway 的 watch 进程，使用命名的 tmux session，并在交互式终端自动附加。非交互式 shell 会保持 detached 并打印 tmux attach -t openclaw-gateway-watch-main；设置 OPENCLAW_GATEWAY_WATCH_ATTACH=0 可以在交互式终端中保持分离，或使用 pnpm gateway:watch:raw 以前台 watch 模式运行。watcher 在相关源码、配置和内置插件元数据变更时自动重载。如果 Gateway 在启动期间退出，gateway:watch 会自动执行 openclaw doctor --fix --non-interactive 一次并重试；设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 可禁用该开发者专用修复步骤。

gateway:watch 不重建 dist/control-ui，所以如果你修改了 ui/ 目录，需要重新运行 pnpm ui:build，或者在开发 Control UI 时使用 pnpm ui:dev。

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>/agent/auth-profiles.json
  • 会话：~/.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/&lt;channel&gt;-<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 仓库。
• 更新源码：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 助手设置
• macOS 应用（Gateway 生命周期说明）

常见问题

为什么 Gateway 启动后 macOS App 显示连接失败？

检查 App 中的 Connection Mode 是否设为 Local，且 Gateway 运行的端口与 App 配置一致（默认 ws://127.0.0.1:18789）。确保终端中的 Gateway 已经启动（openclaw health 应输出正常状态）。

Linux 上 Gateway 每次启动后退出，怎么解决？

这是 systemd 用户服务的默认行为：用户登出后服务被停止。执行 sudo loginctl enable-linger $USER 启用常驻即可。若仍不生效，考虑改用系统服务（参见 Gateway 运维手册）。

更新 OpenClaw 后我的自定义配置会丢失吗？

如果你把配置和工作区放在了 ~/.openclaw/ 下（不在 OpenClaw 仓库目录内），git pull 和 pnpm install 不会影响你的自定义文件。更新后只需重新运行 pnpm gateway:watch 即可。