OpenClaw 🦞

设置

设置

如果您是首次设置，请从 入门指南 开始。 有关向导详情，请参阅 引导向导。

最后更新：2026-01-01

TL;DR

  • 定制生活在仓库之外： ~/.openclaw/workspace（工作区）+ ~/.openclaw/openclaw.json（配置）。
  • 稳定工作流： 安装 macOS 应用；让它运行捆绑的 Gateway。
  • 前沿工作流： 通过 pnpm gateway:watch 自己运行 Gateway，然后让 macOS 应用在本地模式下附加。

先决条件（从源代码）

  • Node >=22
  • pnpm
  • Docker（可选；仅用于容器化设置/e2e — 请参阅 Docker）

定制策略（以便更新不会造成伤害）

如果您想要"100% 为我定制"_和_轻松更新，请将您的自定义保存在：

  • 配置： ~/.openclaw/openclaw.json（JSON/JSON5-ish）
  • 工作区： ~/.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 以监视模式运行网关并在 TypeScript 更改时重新加载。

2) 将 macOS 应用指向您运行的 Gateway

在 OpenClaw.app 中：

  • 连接模式：本地 应用将附加到配置端口上运行的网关。

3) 验证

  • 应用内网关状态应显示 "使用现有网关..."
  • 或通过 CLI：
openclaw health

常见陷阱

  • 错误的端口： 网关 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 机器人令牌：配置/环境变量（尚不支持令牌文件）
  • 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（当 lockfile 更改时）+ 继续使用 pnpm gateway:watch。

Linux（systemd 用户服务）

Linux 安装使用 systemd 用户 服务。默认情况下，systemd 在注销/空闲时停止用户 服务，这会杀死 Gateway。引导尝试为您启用 linger（可能提示 sudo）。如果仍然关闭，请运行：

sudo loginctl enable-linger $USER

对于始终在线或多用户服务器，请考虑使用 系统 服务而不是 用户服务（不需要 linger）。请参阅 Gateway 运行手册 获取 systemd 说明。

相关文档