安装配置

最后更新：2026-01-01

快速总结

  • 个性化配置放在仓库外：~/.openclaw/workspace（工作空间）+ ~/.openclaw/openclaw.json（配置文件）
  • 稳定工作流：安装 macOS 应用，让它运行内置的 Gateway
  • 前沿开发工作流：自己运行 Gateway（通过 pnpm gateway:watch），然后让 macOS 应用以 Local 模式连接

前置要求（从源码安装）

  • Node >=22
  • pnpm
  • Docker（可选；仅用于容器化安装和端到端测试 — 参见 Docker）

个性化配置策略（让更新不再痛苦）

如果你想要”100% 个性化定制”同时又能轻松更新，把你的自定义内容放在：

  • 配置文件：~/.openclaw/openclaw.json（JSON/JSON5 格式）
  • 工作空间：~/.openclaw/workspace（存放 skills、prompts、memories；建议设为私有 git 仓库）

首次初始化：

openclaw setup

如果你在仓库内部，使用本地 CLI 入口：

openclaw setup

如果还没有全局安装，通过 pnpm openclaw setup 运行。

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

  1. 安装并启动 OpenClaw.app（菜单栏应用）
  2. 完成引导和权限检查清单（TCC 权限提示）
  3. 确保 Gateway 设为 Local 并正在运行（应用会自动管理）
  4. 连接通信渠道（例如 WhatsApp）：
openclaw channels login
  1. 健康检查：
openclaw health

如果你的版本没有引导功能：

  • 依次运行 openclaw setup、openclaw channels login，然后手动启动 Gateway（openclaw gateway）

前沿开发工作流（在终端运行 Gateway）

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

0) （可选）从源码运行 macOS 应用

如果你也想让 macOS 应用使用最新开发版：

./scripts/restart-mac.sh

1) 启动开发版 Gateway

pnpm install
pnpm gateway:watch

gateway:watch 会以监听模式运行 Gateway，TypeScript 代码变更时自动重载。

2) 让 macOS 应用连接到你运行的 Gateway

在 OpenClaw.app 中：

  • Connection Mode：Local 应用会连接到配置端口上运行的 Gateway

3) 验证

  • 应用内 Gateway 状态应显示 “Using existing gateway …”
  • 或通过 CLI 检查：
openclaw health

常见问题

  • 端口错误：Gateway WebSocket 默认为 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：config/env 或 channels.telegram.tokenFile
  • Discord bot token：config/env（暂不支持 token 文件）
  • Slack tokens：config/env（channels.slack.*）
  • 配对白名单：~/.openclaw/credentials/<channel>-allowFrom.json
  • 模型认证配置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json 更多详情：安全

更新（不破坏现有配置）

  • 把 ~/.openclaw/workspace 和 ~/.openclaw/ 当作”你的东西”；不要把个人 prompts 和配置放进 openclaw 仓库
  • 更新源码：git pull + pnpm install（当 lockfile 变更时）+ 继续使用 pnpm gateway:watch

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户服务。默认情况下，systemd 会在登出或空闲时停止用户服务，这会杀掉 Gateway。引导程序会尝试为你启用 lingering（可能需要 sudo 权限）。如果仍未启用，运行：

sudo loginctl enable-linger $USER

对于常驻或多用户服务器，考虑使用 系统服务而非用户服务（无需 lingering）。参见 Gateway 运维手册 了解 systemd 相关说明。

相关文档