Skip to main content

​
设置

如果您是第一次设置，请从 入门指南 开始。 关于向导的详细信息，请参见 入职向导。
最后更新：2026-01-01

​
简要说明（TL;DR）

  • 个性化内容放在仓库外： ~/.openclaw/workspace（工作区）+ ~/.openclaw/openclaw.json（配置）。
  • 稳定工作流： 安装 macOS 应用；让它运行捆绑的 Gateway。
  • 前沿工作流： 自行通过 pnpm gateway:watch 运行 Gateway，然后让 macOS 应用以本地模式连接。

​
前置条件（从源码）

  • Node >=22
  • pnpm
  • Docker（可选，仅用于容器化设置/端到端测试 — 参见 Docker）

​
个性化策略（避免更新破坏设置）

如果你想要“100% 量身定制”且便于更新，请将你的定制内容保存在：
  • 配置： ~/.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 应用）

  1. 安装并启动 OpenClaw.app（菜单栏）。
  2. 完成入职流程/权限检查（TCC 提示）。
  3. 确保 Gateway 处于 本地 模式并正在运行（由应用管理）。
  4. 连接渠道（示例：WhatsApp）：
openclaw channels login
  1. 健康检查：
openclaw health
如果你的构建版本中没有入职流程：
  • 运行 openclaw setup，接着执行 openclaw channels login，然后手动启动 Gateway（openclaw gateway）。

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

目标：开发 TypeScript Gateway，支持热重载，并让 macOS 应用UI保持连接。

​
0）【可选】也从源码运行 macOS 应用

如果你也想运行前沿版本的 macOS 应用： 
./scripts/restart-mac.sh

​
1）启动开发模式 Gateway

pnpm install
pnpm gateway:watch
gateway:watch 命令以监听模式运行 Gateway，TypeScript 代码改动时自动重载。

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

在 OpenClaw.app 中：
  • 连接模式：本地 应用将自动连接到配置端口上的运行中 Gateway。

​
3）验证

  • 应用内 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 机器人令牌： 配置文件/环境变量 或 channels.telegram.tokenFile
  • Discord 机器人令牌： 配置文件/环境变量 或 SecretRef（环境变量/文件/执行提供者）
  • Slack 令牌： 配置文件/环境变量（channels.slack.*）
  • 配对允许列表：
    • ~/.openclaw/credentials/<channel>-allowFrom.json（默认账号）
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认账号）
  • 模型认证配置文件： ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 文件支持的秘密载荷（可选）： ~/.openclaw/secrets.json
  • 旧版 OAuth 导入： ~/.openclaw/credentials/oauth.json 详细信息见：安全性。

​
更新（不破坏现有设置）

  • 保持 ~/.openclaw/workspace 和 ~/.openclaw/ 为“你的内容”；不要将个人提示或配置放入 openclaw 仓库中。
  • 更新源码执行 git pull + pnpm install（当锁文件变更时），然后继续使用 pnpm gateway:watch。

​
Linux（systemd 用户服务）

Linux 安装使用 systemd 用户服务。默认情况下，systemd 会在注销/空闲时停止用户服务，导致 Gateway 被终止。入职流程会尝试为你启用 lingering（可能会提示输入 sudo 密码）。如果仍未启用，请执行： 
sudo loginctl enable-linger $USER
对于需要常驻或多用户的服务器，建议使用 系统服务而不是用户服务（无需启用 lingering）。详见 Gateway 运行手册 中的 systemd 说明。

​
相关文档