跳转至

设置

Note

如果你是首次设置，请从 入门指南 开始。 有关初始化引导的详细信息，请参阅 Onboarding (CLI)。

快速了解

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

  • 定制内容保留在仓库之外： 将你的配置和工作区存放在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace/ 中，这样仓库更新不会影响它们。
  • 稳定工作流（适合大多数人）： 安装 macOS 应用，并让它运行自带的 Gateway。
  • 前沿工作流（开发人员）： 通过 pnpm gateway:watch 自行运行 Gateway，然后让 macOS 应用以 Local 模式连接。

先决条件（从源码）

  • Node 24.16+ LTS 或 Node 26.1+（推荐）
  • pnpm 是源码签出（source checkouts）所必需的。OpenClaw 在开发模式下会从 extensions/* pnpm 工作区包加载捆绑插件，因此根目录的 npm install 无法准备完整的源码树。
  • Docker（可选；仅用于容器化安装/端到端测试——参见 Docker）

请使用 package.json 中固定的 pnpm 版本。工作区对 npm 依赖项实施七天的发布冷却期（publication cooldown），但受信任的 @openai/codex 和 @openai/codex-* 包除外。独立的 pnpm 工具链会单独管理。

对于读取项目 .npmrc 的 npm 工具，请使用 npm 11.19 或更高版本来进行安装和 npm pack 冷却期处理，以及 Codex 排除。Node 运行时支持并不表示其自带的 npm 可作为源码解析器（source resolver）。发布/全局安装 不会继承仓库的 .npmrc。源码安装则继续使用 pnpm。

pnpm 管理根目录和插件本地依赖，包括工作区链接以及不同包之间版本差异。Postinstall 和构建准备会保留这些依赖树。如果旧签出裁剪了插件本地依赖，请在更新后运行 pnpm install --frozen-lockfile 以在测试前恢复它们。

定制策略（让更新不伤配置）

如果你想要“100% 为我定制”并且易于更新，请将你的自定义内容放在：

  • 配置： ~/.openclaw/openclaw.json（类似于 JSON/JSON5）
  • 工作区： ~/.openclaw/workspace（技能、prompts、记忆；建议将其设为私有 git 仓库）

只需初始化一次配置/工作区文件夹，无需运行完整的初始化引导向导：

openclaw setup --baseline

还没有全局安装？可以在此仓库中运行：

pnpm openclaw setup --baseline

（单独的 openclaw setup，不带 --baseline，会在已配置的系统上打开交互式 OpenClaw 聊天；如果是全新系统，则会落入引导式初始化流程。完整的路由顺序参见 设置 CLI。）

从本仓库运行 Gateway

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

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

稳定工作流（以 macOS 应用为先）

  1. 安装并启动 OpenClaw.app（菜单栏）。
  2. 完成初始化/权限检查清单（TCC 提示）。
  3. 确保 Gateway 为 Local 并且正在运行（应用会管理它）。
  4. 连接渠道（例如 WhatsApp）：
openclaw channels login
  1. 进行快速验证：
openclaw health

如果你的构建版本中没有初始化引导：

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

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

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

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

如果你也希望 macOS 应用保持前沿版本：

./scripts/restart-mac.sh

1) 启动开发版 Gateway

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

gateway:watch 的作用：

  • 它会在名为 openclaw-gateway-watch-main 的 tmux 会话中启动或重启 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 openclaw ... 或 pnpm gateway:watch 触发的 TypeScript 重建会保留现有的 dist/control-ui 资源。Gateway 启动时，会在提供这些资源之前重新构建缺失、不完整或过期的捆绑 UI 资源。无头命令（headless commands）不会重建 UI。修改 ui/ 后请运行 pnpm ui:build，或在开发 Control UI 时使用 pnpm ui:dev。

2) 将 macOS 应用指向正在运行的 Gateway

在 OpenClaw.app 中：

  • 连接模式：Local 应用将连接到配置端口上正在运行的 Gateway。

3) 验证

  • 应用内 Gateway 状态应显示 “Using existing gateway …”
  • 或通过 CLI：
openclaw health

常见陷阱

  • 端口错误： Gateway WS 默认使用 ws://127.0.0.1:18789；请让应用和 CLI 使用同一端口。
  • 开发者 CLI 选错： 当 PATH 中包含 node_modules/.bin 时，codex 可能会解析到工作区固定的 CLI，而不是你的独立安装。对于开发工作进程（developer workers），请对 --version 和 exec 都使用目标可执行文件的绝对路径，并确认工作进程的启动版本。包清单或另一个 shell 中的版本检查无法识别正在运行的工作进程。OpenClaw 的 托管 Codex app-server 有单独的固定版本契约；不要为了修复开发者 CLI 选择问题而更改该固定版本或你的模型/认证设置。如果安装的工作区包与本机可执行文件与锁文件不一致，请使用 pnpm install 修复安装，而不是编辑 node_modules。
  • 状态存储位置：
  • 渠道/提供商状态：~/.openclaw/credentials/
  • 模型认证配置文件：SQLite 认证存储（共享：~/.openclaw/state/openclaw.sqlite；代理本地：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite）
  • 会话和记录：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
  • 旧版/归档会话产物：~/.openclaw/agents/<agentId>/sessions/
  • 日志：/tmp/openclaw/

凭据存储映射

在调试身份验证或决定要备份哪些内容时，可使用此映射：

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram 机器人 Token: config/env 或 channels.telegram.tokenFile（仅普通文件；拒绝符号链接）
  • Discord 机器人 Token: config/env 或 SecretRef（env/file/exec/store 提供程序）
  • Slack Token: config/env（channels.slack.*）
  • 配对允许列表:
  • ~/.openclaw/credentials/<channel>-allowFrom.json（默认账户）
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账户）
  • 模型身份验证配置文件: 共享和 agent 本地 SQLite 身份验证存储；有关继承和旧版共享存储迁移，请参阅 身份验证凭据语义
  • 基于文件的 secrets 负载（可选）: ~/.openclaw/secrets.json
  • 旧版 OAuth 导入: ~/.openclaw/credentials/oauth.json 更多详情：安全。

更新（不会破坏你的配置）

  • 将 ~/.openclaw/workspace 和 ~/.openclaw/ 保留为“你的内容”；不要将个人 Prompt/配置放入 openclaw 仓库。
  • 更新源代码：git pull + pnpm install + 继续使用 pnpm gateway:watch。

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户 服务。默认情况下，systemd 会在注销/空闲时停止用户 服务，从而终止 Gateway。引导流程会尝试为你启用 lingering（可能会提示输入 sudo）。如果它仍处于关闭状态，请运行：

sudo loginctl enable-linger $USER

对于始终在线或多用户服务器，请考虑使用 系统 服务而不是 用户服务（无需 lingering）。有关 systemd 说明，请参阅 Gateway 运行手册。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw