设置
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 向导:
还没有全局安装?可以改为从本仓库运行:
不带 --baseline 的裸 openclaw setup 会在已配置的系统上打开一个交互式 OpenClaw 聊天;在全新系统上则会转入引导式 onboarding。完整的路由顺序请参阅 Setup CLI。
从本仓库运行 Gateway¶
在 pnpm build 之后,你可以直接运行打包好的 CLI:
稳定工作流(macOS 应用优先)¶
- 安装并启动 OpenClaw.app(菜单栏应用)。
- 完成 onboarding/权限检查清单(TCC 权限提示)。
- 确保 Gateway 为 Local 且正在运行(由应用管理)。
- 连接各接入渠道(例如 WhatsApp):
- 健康检查:
如果你的构建不包含 onboarding:
- 先运行
openclaw setup,再运行openclaw channels login,然后手动启动 Gateway(openclaw gateway)。
前沿工作流(在终端中运行 Gateway)¶
目标:开发 TypeScript Gateway,获得热重载,并让 macOS 应用 UI 保持连接。
0)(可选)也通过源码运行 macOS 应用¶
如果你也希望 macOS 应用处于前沿版本:
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:
常见踩坑点¶
- 端口错误: 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)。如果仍未启用,请运行:
对于始终在线或多用户服务器,请考虑使用 系统 服务而不是用户 服务(无需 lingering)。有关 systemd 说明,请参阅 Gateway 运行手册。
相关文档¶
- Gateway 运行手册(标志、监管、端口)
- Gateway 配置(配置模式 + 示例)
- Discord 和 Telegram(回复标签 + replyToMode 设置)
- OpenClaw 助手设置
- macOS 应用(Gateway 生命周期)
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw