OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

开发者设置

设置

简要说明

根据你希望更新的频率以及是否希望自行运行 Gateway 网关，选择设置工作流：

  • **定制内容应放在仓库外：**将配置和工作区保存在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace/ 中，以免仓库更新影响它们。
  • **稳定版工作流（建议大多数用户使用）：**安装 macOS 应用，并让它运行内置的 Gateway 网关。
  • **前沿版工作流（开发）：**通过 pnpm gateway:watch 自行运行 Gateway 网关，然后让 macOS 应用以 Local 模式连接。

前置要求（从源码运行）

  • 建议使用 Node 24.15+（仍支持 Node 22 LTS，当前版本为 22.22.3+）
  • 从源码检出时需要 pnpm。在开发模式下，OpenClaw 会从 extensions/* pnpm 工作区软件包加载内置插件，因此根目录的 npm install 不会准备完整的源码树。
  • Docker（可选；仅用于容器化设置/E2E——参阅 Docker）

定制策略（避免更新造成破坏）

如果希望“完全按我的需求定制”_同时_又便于更新，请将自定义内容保存在：

  • 配置：~/.openclaw/openclaw.json（类似 JSON/JSON5）
  • 工作区：~/.openclaw/workspace（Skills、提示词、记忆；建议将其设为私有 Git 仓库）

仅初始化一次配置和工作区文件夹，而不运行完整的新手引导向导：

bash
openclaw setup --baseline

尚未全局安装？请改为从此仓库运行：

bash
pnpm openclaw setup --baseline

（不带 --baseline 的纯 openclaw setup 是 openclaw onboard 的别名，会运行完整的交互式向导。）

从此仓库运行 Gateway 网关

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

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

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

  1. 安装并启动 OpenClaw.app（菜单栏）。
  2. 完成新手引导/权限检查清单（TCC 提示）。
  3. 确保 Gateway 网关为 Local 且正在运行（由应用管理）。
  4. 关联渠道（例如 WhatsApp）：
bash
openclaw channels login
  1. 执行完整性检查：
bash
openclaw health

如果你的构建版本不提供新手引导：

  • 依次运行 openclaw setup 和 openclaw channels login，然后手动启动 Gateway 网关（openclaw gateway）。

前沿版工作流（在终端中运行 Gateway 网关）

目标：开发 TypeScript Gateway 网关、获得热重载，并保持 macOS 应用 UI 与之连接。

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

如果还希望使用前沿版 macOS 应用：

bash
./scripts/restart-mac.sh

1) 启动开发版 Gateway 网关

bash
pnpm install# 仅首次运行时需要（或重置本地 OpenClaw 配置/工作区后）pnpm openclaw setuppnpm gateway:watch

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

  • Connection Mode：Local 应用将连接到配置端口上正在运行的 Gateway 网关。

3) 验证

  • 应用内的 Gateway 网关状态应显示 "Using existing gateway …"
  • 也可以通过 CLI 验证：
bash
openclaw health

常见陷阱

  • **端口错误：**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 Bot 令牌：配置/环境变量或 channels.telegram.tokenFile（只能是普通文件；拒绝符号链接）
  • Discord Bot 令牌：配置/环境变量或 SecretRef（环境变量/文件/exec 提供商）
  • Slack 令牌：配置/环境变量（channels.slack.*）
  • 配对允许列表：
    • ~/.openclaw/credentials/<channel>-allowFrom.json（默认账户）
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账户）
  • 模型身份验证配置文件：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 基于文件的密钥载荷（可选）：~/.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）。如果仍未启用，请运行：

bash
sudo loginctl enable-linger $USER

对于需要持续运行或支持多用户的服务器，请考虑使用系统服务而非用户服务（无需 lingering）。有关 systemd 的说明，请参阅 Gateway 网关运行手册。

相关文档

Was this useful?
On this page

On this page