设置

如果是第一次设置，请从[入门指南](/zh/docs/start/getting-started)开始。 有关向导详情，参见[入门向导](/zh/docs/start/wizard)。

最后更新：2026-01-01

简而言之

  • 定制位于仓库之外：~/.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. 完成 onboarding/权限检查清单（TCC 提示）。
  3. 确保 Gateway 是本地且正在运行（应用管理它）。
  4. 连接 surface（示例：WhatsApp）：
openclaw channels login
  1. 健全性检查：
openclaw health

如果你的构建中没有 onboarding：

  • 运行 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 以 watch 模式运行 gateway 并在 TypeScript 更改时重新加载。

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

在 OpenClaw.app 中：

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

3) 验证

  • 应用内 Gateway 状态应显示”使用现有 gateway …”
  • 或通过 CLI：
openclaw health

常见陷阱

  • **错误端口：**Gateway WS 默认为 ws://127.0.0.1:18789；保持应用 + CLI 在同一端口。
  • 状态位置：
    • 凭证：~/.openclaw/credentials/
    • 会话：~/.openclaw/agents/<agentId>/sessions/
    • 日志：/tmp/openclaw/

凭证存储映射

在调试 auth 或决定备份什么时使用此信息：

  • 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/credentials/<channel>-<accountId>-allowFrom.json（非默认账户）
  • 模型 auth profiles：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 文件支持的 secrets 有效载荷（可选）：~/.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。Onboarding 尝试为你启用 lingering（可能会提示输入 sudo）。如果仍然关闭，运行：

sudo loginctl enable-linger $USER

对于常驻或多用户服务器，请考虑使用系统服务而不是用户服务（不需要 lingering）。有关 systemd 说明，参见 Gateway 运行手册。

相关文档