安装后设置

核心原则

• 你的个人设置存放在仓库之外：~/.openclaw/workspace（工作区）+ ~/.openclaw/openclaw.json（配置）
• 稳定使用：安装 macOS 应用，让它管理内置的 Gateway
• 开发/贡献：通过 pnpm gateway:watch 自己运行 Gateway，让 macOS 应用以本地模式连接

---

个性化配置策略

想要配置完全个性化，又不担心升级时被覆盖？把自定义内容放在：

• 配置文件：~/.openclaw/openclaw.json（JSON / JSON5 格式）
• 工作区：~/.openclaw/workspace（Skills、Prompt、记忆；建议设为私有 Git 仓库）

初始化一次即可：

openclaw setup

---

稳定工作流（macOS 应用优先）

1. 安装并启动 OpenClaw.app（菜单栏）

2. 完成新手引导和权限检查清单（TCC 提示）

3. 确认 Gateway 为本地模式并正在运行（应用自动管理）

4. 连接渠道：

   openclaw channels login

5. 完整性检查：

   openclaw health

如果你的构建版本没有内置新手引导：

openclaw setup
openclaw channels login
openclaw gateway   # 手动启动 Gateway

---

开发工作流（前台运行 Gateway）

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

1）启动开发 Gateway

pnpm install
pnpm gateway:watch

gateway:watch 以监视模式运行，TypeScript 改动后自动重载。

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

在 OpenClaw.app 中：

• 连接模式改为 本地（Local）

应用会连接到配置端口上运行的 Gateway。

3）验证

• 应用内 Gateway 状态应显示 "Using existing gateway …"

• 或通过 CLI：

  openclaw health

常见陷阱

• 端口不一致：Gateway WS 默认 ws://127.0.0.1:18789，确保应用和 CLI 使用相同端口
• 状态存储位置：
  • 凭证：~/.openclaw/credentials/
  • 会话：~/.openclaw/agents/<agentId>/sessions/
  • 日志：/tmp/openclaw/

---

凭证存储位置

调试认证问题或规划备份时参考：

内容	路径
WhatsApp 凭证	~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram Bot Token	配置文件或环境变量（channels.telegram.tokenFile）
Discord Bot Token	配置文件或环境变量（不支持 token 文件）
Slack Tokens	配置文件或环境变量（channels.slack.*）
配对允许列表	~/.openclaw/credentials/<channel>-allowFrom.json
模型认证配置	~/.openclaw/agents/<agentId>/agent/auth-profiles.json
旧版 OAuth 导入	~/.openclaw/credentials/oauth.json

---

更新（不破坏个人配置）

• 把 ~/.openclaw/workspace 和 ~/.openclaw/openclaw.json 当作「你的文件」，不要放到 openclaw 仓库里

• 更新源码：

  git pull
  pnpm install   # 仅在 lock 文件有变化时
  pnpm gateway:watch   # 继续开发

---

Linux systemd 用户服务注意事项

Linux 安装使用 systemd 用户服务。默认情况下，systemd 在注销/空闲时停止用户服务，导致 Gateway 被终止。新手引导会自动尝试启用 lingering，如果 Gateway 仍然会停止，手动运行：

sudo loginctl enable-linger $USER

对于常驻或多用户服务器，考虑改用 systemd 系统服务（不需要 lingering）。

---

相关文档

• Gateway 配置参考
• 渠道接入
• 快速入门