Skip to main content
如果你是第一次设置，请先从 快速开始 开始。 有关入门详情，请参阅 入门（CLI）。

​
TL;DR

根据你希望更新的频率以及是否想自己运行 Gateway，选择一种设置工作流：
  • 定制化存在于仓库之外： 将你的配置和工作区保存在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace/ 中，这样仓库更新就不会影响它们。
  • 稳定工作流（推荐给大多数人）： 安装 macOS 应用并让它运行内置的 Gateway。
  • 前沿工作流（开发）： 通过 pnpm gateway:watch 自己运行 Gateway，然后让 macOS 应用以本地模式连接。

​
前置条件（从源码）

  • 推荐使用 Node 24.15+（仍支持 Node 22 LTS，目前为 22.22.3+）
  • 源码检出需要 pnpm。OpenClaw 在开发模式下会从 extensions/* pnpm workspace 包中加载捆绑插件，因此根目录下的 npm install 不会准备完整的源码树。
  • Docker（可选；仅用于容器化设置/e2e - 参见 Docker）。

​
定制化策略（让更新不会伤到你）

如果你想要“完全按我的需求定制”，同时又希望轻松更新，请将你的定制内容保存在：
  • 配置： ~/.openclaw/openclaw.json（JSON/JSON5 风格）
  • 工作区： ~/.openclaw/workspace（技能、提示词、记忆；建议将其设为私有 git 仓库）
首次初始化 config/workspace 文件夹，而不运行完整的 onboarding 向导：
还没有全局安装？那就从这个仓库中运行：
（不带 --baseline 的 openclaw setup 是 openclaw onboard 的别名，会运行完整的交互式向导。）

​
从本仓库运行 Gateway

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

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

  1. 安装并启动 OpenClaw.app（菜单栏应用）。
  2. 完成入门/权限检查清单（TCC 提示）。
  3. 确保 Gateway 处于 本地 且正在运行（由应用管理它）。
  4. 连接各个渠道（示例：WhatsApp）：
  1. 健康检查：
如果你的构建版本中没有入门流程：
  • 运行 openclaw setup，然后运行 openclaw channels login，最后手动启动 Gateway（openclaw gateway）。

​
前沿工作流（在终端中运行 Gateway）

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

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

如果你也想让 macOS 应用走前沿版本：

​
1）启动开发版 Gateway

gateway:watch 会在一个命名的 tmux 会话（openclaw-gateway-watch-main）中启动或重启 Gateway 监视进程，并在交互式终端中自动附加。非交互式 shell 会保持分离，并打印 tmux attach -t openclaw-gateway-watch-main；使用 OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch 可让交互式运行保持分离，或使用 pnpm gateway:watch:raw 以进入前台监视模式。监视器会在接管其配置的/默认端口之前停止当前活动配置文件中已安装的 Gateway 服务，防止服务监督器用源进程替换它。 该服务仍会保持安装状态；完成监视后运行 pnpm openclaw gateway start。 即使启动失败，tmux 窗格也会保持可用，因此另一个终端或代理可以附加或获取其日志。监视器会在相关源码、配置和打包插件元数据变化时重新加载。如果被监视的 Gateway 在启动期间退出，gateway:watch 会先运行一次 openclaw doctor --fix --non-interactive，然后重试；设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 可禁用该仅用于开发的修复流程。 pnpm gateway:watch 不会重建 dist/control-ui，因此在 ui/ 变更后请重新运行 pnpm ui:build，或者在开发 Control UI 时使用 pnpm ui:dev。

​
2）将 macOS 应用指向你正在运行的 Gateway

在 OpenClaw.app 中：
  • 连接模式：本地 应用将连接到已在配置端口上运行的 gateway。

​
3）验证

  • 应用内的 Gateway 状态应显示 “使用现有 gateway …”
  • 或通过 CLI：

​
常见坑

  • 端口错误： Gateway WS 默认为 ws://127.0.0.1:18789；请让应用 + CLI 使用同一个端口。
  • 状态存储位置：
    • 频道/提供商状态：~/.openclaw/credentials/
    • 模型身份验证配置文件：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • 会话和记录：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
    • 旧版/归档会话工件：~/.openclaw/agents/<agentId>/sessions/
    • 日志：/tmp/openclaw/

​
凭据存储映射

调试认证或决定要备份哪些内容时可参考这里：
  • WhatsApp：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram 机器人令牌：config/env 或 channels.telegram.tokenFile（仅限常规文件；拒绝符号链接）
  • Discord 机器人令牌：config/env 或 SecretRef（env/file/exec/store 提供程序）
  • Slack 令牌：config/env（channels.slack.*）
  • 配对允许列表：
    • ~/.openclaw/credentials/<channel>-allowFrom.json（默认账户）
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账户）
  • 模型认证配置文件：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 文件支持的 secrets 负载（可选）：~/.openclaw/secrets.json
  • 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json 更多详情：安全。

​
更新（不破坏你的设置）

  • 将 ~/.openclaw/workspace 和 ~/.openclaw/ 视为“你的内容”；不要把个人提示词/配置放进 openclaw 仓库。
  • 更新源码：git pull + pnpm install + 继续使用 pnpm gateway:watch。

​
Linux（systemd 用户服务）

Linux 安装使用 systemd 用户 服务。默认情况下，systemd 会在注销／空闲时停止用户服务，这会杀死 Gateway。入门流程会尝试为你启用 lingering（可能会提示输入 sudo）。如果仍然未启用，请运行：
对于始终在线或多用户服务器，考虑使用 系统 服务而不是 用户服务（无需 lingering）。有关 systemd 说明，请参见 Gateway 操作手册。

​
相关文档