跳转至

设置

Note

如果你是首次设置,请从 快速入门 开始。 有关入门引导的详细信息,请参阅 入门引导(CLI)。

TL;DR

根据你希望更新的频率、以及是否自己运行 Gateway,选择一种设置工作流:

  • 定制内容位于仓库之外: 将配置和工作区放在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace/ 中,这样仓库更新不会影响它们。
  • 稳定工作流(推荐大多数人使用): 安装 macOS 应用,并让它运行内置的 Gateway。
  • 前沿工作流(开发): 通过 pnpm gateway:watch 自己运行 Gateway,然后让 macOS 应用以 Local 模式附加连接。

前提条件(源码构建)

  • Node 24.16+ LTS 或 Node 26.1+(推荐)
  • 源码检出需要 pnpm。在 dev 模式下,OpenClaw 会从 extensions/* pnpm 工作区包加载内置插件,因此在根目录执行 npm install 无法准备完整的源码树。
  • Docker(可选;仅用于容器化设置/e2e——参见 Docker)

使用 package.json 中固定的 pnpm 版本。工作区对 npm 依赖实施七天的发布冷却期,受信任的 @openai/codex 和 @openai/codex-* 包除外。独立的 pnpm 工具链另行管理。

对于读取项目 .npmrc 的 npm 工具,安装、npm pack 冷却期以及 Codex 排除规则请使用 npm 11.19 或更高版本。对 Node 运行时的支持并不意味着其内置的 npm 可作为源码解析器得到支持。发布/全局安装 不会继承仓库的 .npmrc。源码安装继续使用 pnpm。

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

定制策略(让更新不伤配置)

如果你想要“100% 为我量身定制” 并且 还能轻松更新,就把自定义内容放在:

  • 配置: ~/.openclaw/openclaw.json(类似 JSON/JSON5)
  • 工作区: ~/.openclaw/workspace(技能、提示词、记忆;建议设为私有 git 仓库)

只需初始化一次 config/workspace 文件夹,无需运行完整的 onboarding 向导:

openclaw setup --baseline

还没有全局安装?可以改为从本仓库运行:

pnpm openclaw setup --baseline

不带 --baseline 的裸 openclaw setup 会在已配置的系统上打开一个交互式 OpenClaw 聊天;在全新系统上则会转入引导式 onboarding。完整的路由顺序请参阅 Setup CLI。

从本仓库运行 Gateway

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

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

稳定工作流(macOS 应用优先)

  1. 安装并启动 OpenClaw.app(菜单栏应用)。
  2. 完成 onboarding/权限检查清单(TCC 权限提示)。
  3. 确保 Gateway 为 Local 且正在运行(由应用管理)。
  4. 连接各接入渠道(例如 WhatsApp):
openclaw channels login
  1. 健康检查:
openclaw health

如果你的构建不包含 onboarding:

  • 先运行 openclaw setup,再运行 openclaw channels login,然后手动启动 Gateway(openclaw gateway)。

前沿工作流(在终端中运行 Gateway)

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

0)(可选)也通过源码运行 macOS 应用

如果你也希望 macOS 应用处于前沿版本:

./scripts/restart-mac.sh

1) 启动开发 Gateway

pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch

gateway:watch 的具体行为:

  • 它会在名为 openclaw-gateway-watch-main 的 tmux 会话中启动或重启 Gateway watch 进程,并在交互式终端中自动附加(attach)。
  • 非交互式 shell 会保持分离状态,并打印 tmux attach -t openclaw-gateway-watch-main。运行 OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch 可以让交互式运行保持分离;pnpm gateway:watch:raw 则用于前台 watch 模式。
  • 在接管该服务已配置或默认端口之前,它会先停止当前 profile 已安装的 Gateway 服务。这可以防止服务监督器替换源码进程。该服务仍保持安装状态。结束 watch 后,运行 pnpm openclaw gateway start 即可。
  • 启动失败后 tmux 窗格仍然可用,因此其他终端或 agent 可以附加到它,或捕获其日志。
  • 当相关源码、配置和内置插件元数据发生变化时,它会重新加载。
  • 如果被 watch 的 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 资源。UI 构建只有在完整 bundle 通过验证后才会替换 dist/control-ui,因此构建失败时,之前的 bundle 会保留在原处。如果构建在替换其输出时被终止,下一次构建会先恢复之前的 bundle。无头命令不会重建 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,而不是你的独立安装。对于开发者 worker,请在 --version 和 exec 中都使用目标可执行文件的绝对路径,并确认 worker 启动时的版本。包清单或其他 shell 中的版本检查无法识别正在运行的 worker。OpenClaw 的 托管 Codex app-server 有单独的固定版本契约;不要为了修复开发者 CLI 选择而更改该固定版本或你的模型/认证设置。如果已安装的工作区包和原生可执行文件与 lockfile 不一致,请用 pnpm install 修复安装,而不是编辑 node_modules。
  • 状态存放在哪里:
  • 渠道/提供方状态:~/.openclaw/credentials/
  • 模型认证配置:SQLite 认证存储(共享:~/.openclaw/state/openclaw.sqlite;agent 本地:~/.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(非默认账户)
  • 模型身份验证配置文件:共享和代理本地 SQLite 身份验证存储;有关继承和旧版共享存储迁移,请参阅 身份验证凭据语义
  • 基于文件的密钥负载(可选):~/.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