安装与配置
安装与配置指南：在持续更新的同时保持你的 OpenClaw 个人化设置。
最后更新：2026-01-01
TL;DR
- **个性化配置放在仓库外：** `~/.openclaw/workspace`（工作区）+ `~/.openclaw/openclaw.json`（配置）。
- **稳定工作流：** 安装 macOS 应用，让它运行自带的 Gateway。
- **前沿工作流：** 使用 `pnpm gateway:watch` 自己跑 Gateway，再让 macOS 应用以本机模式连接。
前置条件（从源码运行）
个性化策略（让更新不伤人）
如果你希望 “100% 为我定制” 且能轻松更新，把自定义内容放在：
- **配置：** `~/.openclaw/openclaw.json`（JSON/JSON5 风格）
- **工作区：** `~/.openclaw/workspace`（技能、提示词、记忆；建议做成私有 git 仓库）
首次自举：
openclaw setup
在本仓库内，可以使用本地 CLI 入口：
openclaw setup
如果你还没有全局安装，可以用 `pnpm openclaw setup`。
稳定工作流（优先 macOS 应用）
1. 1. 安装并启动 **OpenClaw.app**（菜单栏）。
2. 2. 完成上手引导 / 权限清单（TCC 授权弹窗）。
3. 3. 确认 Gateway 处于 **本机** 模式并在运行（由应用管理）。
4. 4. 连接聊天平台（示例：WhatsApp）：
openclaw channels login
5. 5. 健康检查：
openclaw health
如果你的构建版本没有上手引导：
- 依次运行 `openclaw setup`、`openclaw channels login`，然后手动启动 Gateway（`openclaw gateway`）。
前沿工作流（终端里跑 Gateway）
目标：开发 TypeScript Gateway，获得热重载，同时让 macOS 应用 UI 连接到你的 Gateway。
0）（可选）也从源码运行 macOS 应用
如果你也想使用最新的 macOS 应用：
./scripts/restart-mac.sh
1）启动开发 Gateway
pnpm install pnpm gateway:watch
`gateway:watch` 会以 watch 模式运行 gateway，在 TypeScript 变更时自动重载。
2）让 macOS 应用连接到正在运行的 Gateway
在 **OpenClaw.app** 中：
- Connection Mode：选择 **Local**
应用会连接到配置端口上正在运行的 gateway。
3）验证
- 应用内 Gateway 状态应显示 **“Using existing gateway …”**
- 或使用 CLI：
openclaw health
常见踩坑点
- **端口不一致：** Gateway WS 默认 `ws://127.0.0.1:18789`；应用与 CLI 必须使用同一端口。
- **状态保存位置：**
- 凭据：`~/.openclaw/credentials/`
- 会话：`<code1>~/.openclaw/agents/<agentId>/sessions/</code1>`
- 日志：`/tmp/openclaw/`
凭据存储地图
调试鉴权或决定备份内容时可参考：
- **WhatsApp：** `<code1>~/.openclaw/credentials/whatsapp/<accountId>/creds.json</code1>`
- **Telegram bot token：** 配置 / 环境变量，或 `channels.telegram.tokenFile`
- **Discord bot token：** 配置 / 环境变量（暂不支持 token 文件）
- **Slack tokens：** 配置 / 环境变量（`channels.slack.*`）
- **配对 allowlists：** `<code1>~/.openclaw/credentials/<channel>-allowFrom.json</code1>`
- **模型鉴权 profiles：** `<code1>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code1>`
- **旧版 OAuth 导入：** `~/.openclaw/credentials/oauth.json`
更多细节：参见 Security 。
更新（不弄坏你的配置）
- - 把 `~/.openclaw/workspace` 和 `~/.openclaw/` 当作“你的东西”；不要把个人提示词/配置塞进 `openclaw` 仓库。
- - 更新源码：`git pull` + `pnpm install`（lockfile 变更时）+ 继续使用 `pnpm gateway:watch`。
Linux（systemd 用户服务）
Linux 安装使用 systemd 的 **user** 服务。默认情况下，systemd 会在退出登录/空闲时停止用户服务，从而杀掉 Gateway。上手引导会尝试为你启用 lingering（可能会提示 sudo）。如果仍未启用，请运行：
sudo loginctl enable-linger $USER
对于需要常驻或多用户的服务器，考虑使用 **system** 服务而不是 user 服务（无需 lingering）。参见 网关运维手册 中的 systemd 说明。