开发者设置
设置（setup）
最后更新：2026-01-01
速览
- 定制内容放在仓库外面：
~/.openclaw/workspace（工作区）+~/.openclaw/openclaw.json（配置文件）。 - 稳定工作流： 安装 macOS 应用，让它自动运行内置的网关（Gateway）。
- 前沿工作流： 通过
pnpm gateway:watch自己运行网关（Gateway），然后让 macOS 应用以本地模式连接。
前提条件（从源码安装）
- Node
>=22 pnpm- Docker（可选，仅用于容器化设置或端到端测试 — 详见 Docker）
定制策略（让更新不破坏你的配置）
想要「完全为我定制」同时还能轻松更新 ？把你的个性化内容放在以下位置：
- 配置：
~/.openclaw/openclaw.json（JSON 或类 JSON5 格式） - 工作区：
~/.openclaw/workspace（技能、提示词、记忆等；建议设为私有 git 仓库）
执行一次引导命令：
openclaw setup
在仓库内部，可以使用本地 CLI 入口：
openclaw setup
如果还没全局安装，可以通过 pnpm openclaw setup 运行。
从本仓库运行网关（Gateway）
完成 pnpm build 后，可以直接运行打包好的 CLI：
node openclaw.mjs gateway --port 18789 --verbose
稳定工作流（先装 macOS 应用）
- 安装并启动 OpenClaw.app（菜单栏应用）。
- 完成入门向导和权限检查清单（会弹出 TCC 权限提示）。
- 确保网关（Gateway）处于 本地（Local） 模式并正在运行（应用会自动管理）。
- 连接通信渠道（以 WhatsApp 为例）：
openclaw channels login
- 健康检查：
openclaw health
如果你的构建版 本没有入门向导：
- 先运行
openclaw setup，再运行openclaw channels login，最后手动启动网关（Gateway）（openclaw gateway）。
前沿工作流（在终端中运行网关）
目标是：在 TypeScript 版网关（Gateway）上开发，获得热重载能力，同时保持 macOS 应用的 UI 连接。
0）（可选）也从源码运行 macOS 应用
如果你想让 macOS 应用也保持前沿版本：
./scripts/restart-mac.sh
1）启动开发版网关
pnpm install
pnpm gateway:watch
gateway:watch 会以监视模式运行网关（Gateway），TypeScript 代码变更时自动重新加载。
2）让 macOS 应用连接你的网关
在 OpenClaw.app 中：
- 连接模式选择 本地（Local），应用会连接到指定端口上正在运行的网关（Gateway）。
3）验证
- 应用内的网关状态应显示 「正在使用现有 gateway …」
- 或通过 CLI 检查：
openclaw health
常见坑
- 端口搞错了： 网关（Gateway）的 WebSocket 默认使用
ws://127.0.0.1:18789；确保应用和 CLI 使用相同的端口。 - 状态存储在哪：
- 凭证：
~/.openclaw/credentials/ - 会话：
~/.openclaw/agents//sessions/ - 日志：
/tmp/openclaw/
- 凭证：
凭证存储位置一览
调试认证问题或决定备份内容时，可以参考这个清单：
- WhatsApp：
~/.openclaw/credentials/whatsapp//creds.json - Telegram 机器人令牌： 配置文件/环境变量，或
channels.telegram.tokenFile - Discord 机器人令牌： 配置文件/环境变量，或 SecretRef（支持环境变量/文件/命令执行等提供者）
- Slack 令牌： 配置文件/环境变量（
channels.slack.*） - 配对允许列表：
~/.openclaw/credentials/-allowFrom.json（默认账户）~/.openclaw/credentials/--allowFrom.json（非默认账户）
- 模型认证配置：
~/.openclaw/agents//agent/auth-profiles.json - 文件存储的密钥载荷（可选）：
~/.openclaw/secrets.json - 旧版 OAuth 导入：
~/.openclaw/credentials/oauth.json更多 详情见 安全。
更新（别搞坏你的配置）
- 把
~/.openclaw/workspace和~/.openclaw/视为「你的东西」；不要把个人提示词或配置放进openclaw仓库里。 - 更新源码的方法：
git pull+pnpm install（当 lockfile 有变化时）+ 继续用pnpm gateway:watch。
Linux（systemd 用户服务）
Linux 安装使用 systemd 用户服务。默认情况下，systemd 会在用户登出或空闲时停止用户服务，这会终止网关（Gateway）。入门向导会尝试为你启用 lingering（可能需要输入 sudo 密码）。如果还是没启用，运行：
sudo loginctl enable-linger $USER
对于需要常开或多用户的服务器，建议使用 系统服务而非用户服务（不需要 lingering）。详见 网关运行手册 中的 systemd 说明。