分享：OpenClaw Agent 搭建全流程：从本机自托管到可用、可控、可审计的个人 AI 助手

按照官方文档，OpenClaw 是一个 self-hosted gateway，用来把 Discord、Google Chat、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等聊天入口连接到 AI coding agents。它运行在各位自己的机器或服务器上，Gateway 是会话、路由和通道连接的单一事实来源。

这句话里有几个关键词：

Self-hosted
不是把你的全部流程托管给一个外部 SaaS，而是在你的电脑、服务器、VPS 或容器里跑 Gateway。控制权更强，但运维、安全和权限边界也由你负责。

Gateway
OpenClaw 不是单一聊天窗口。Gateway 更像中枢，负责处理通道、会话、模型、工具、节点、Dashboard、路由等问题。

Agent-native
OpenClaw 内置 Agent runtime，包括 agent loop、tool wiring、prompt assembly、session 管理等。每个配置好的 Agent 能够有自己的 workspace、bootstrap files 和 session store。

Multi-channel
你能够通过不同消息入口和 Agent 互动，但这也意味着入口控制非常重要。任何能给 Agent 发消息的人，理论上都可能影响 Agent 后续行为。

3 -> 适合谁，不适合谁

适合：

想要一个自己可控、能长期记忆、能接工具的个人 AI 助手。
想把 AI 助手接到移动端消息软件，做到随时可以发指令。
想把 Codex、Claude、OpenAI、浏览器、文件、脚本、工作流串成一个长期系统。
有一定命令行、Node、配置文件和安全意识。

不适合：

只想偶尔问几个问题，用 ChatGPT、Claude 或普通网页端就够。
不愿意维护本机服务、配置、日志、更新和备份。
想让多个互不信任的人共用一个高权限 Agent。
想直接开放公网、群聊和高权限工具，但没有安全隔离方案。

官方安全文档明确强调，OpenClaw 默认是个人助手信任模型，更适合一个 trusted operator boundary。多个互不信任用户共享同一个 tool-enabled agent，不应该被当成安全隔离边界。

4 -> 整体搭建路线

下面这张图是推荐搭建节奏。不要一开始就把所有通道、所有工具、所有自动化全部打开。先把基础闭环跑稳，再逐步加能力。

4.1 -> 阶段 1：安装 OpenClaw 并启动 Gateway

目标：CLI 可用，Gateway 能启动，Dashboard 能打开。

验收命令：

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

4.2 -> 阶段 2：建立 Agent 工作区

目标：明确这个 Agent 是谁、听谁的、能做什么、不能做什么、怎么记录长期记忆。

核心文件：

AGENTS.md
SOUL.md
USER.md
IDENTITY.md
TOOLS.md
HEARTBEAT.md
MEMORY.md
memory/YYYY-MM-DD.md

4.3 -> 阶段 3：配置模型和通道

目标：Agent 能稳定调用模型，并且只接受授权入口的消息。

重点：

配置 primary model 和 fallbacks。
通道优先使用 pairing 或 allowlist。
群聊默认要求 mention。
不用真实客户或外部用户做第一轮测试。

4.4 -> 阶段 4：开放工具、Skills 和自动化

目标：让 Agent 能做事，但权限可控。

重点：

tools.exec.mode 先用 auto、ask 或 allowlist。
Skills 先按 Agent allowlist 限定。
非 main 会话、群聊、外部通道优先使用 sandbox。

4.5 -> 阶段 5：做审计、日志、备份和回滚

目标：出问题时知道哪里错了，能关掉、能恢复、能追踪。

重点：

openclaw doctor
openclaw security audit
openclaw logs
私有备份 workspace，不提交密钥和会话凭据。

5 -> 准备环境

官方安装文档给出的系统要求是：

Node 22.19+、23.11+ 或 24+，其中 Node 24 是默认目标。
macOS、Linux 或 Windows。
如果从源码构建，需要 pnpm。

实践建议：

1. 新手优先用官方 installer script，让它处理 Node 和初始化。
2. Windows 用户可以选择 PowerShell CLI 安装，也可以先看 Windows Hub companion app。
3. 如果你未来要接高权限工具，建议使用单独的系统用户、单独机器、WSL2、Docker 或 VPS，至少不要和日常浏览器、私人文件混在同一个高权限环境里。
4. 不要在公司生产电脑上直接试验不受控工具权限，先在测试环境搭。

5.1 -> 检查 Node

node -v
npm -v

如果 node -v 不满足版本要求，优先按官方安装器走，或者用你熟悉的 Node 管理方式升级。

6 -> 安装 OpenClaw

6.1 -> 推荐方式：官方安装脚本

macOS / Linux / WSL2：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

如果只想安装，不立即进入 onboarding：

macOS / Linux / WSL2：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows PowerShell：

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

6.2 -> 已经自己管理 Node 时：npm 安装

官方文档也提供 npm、pnpm、bun 等安装方式。为了避免命令粘在一行导致误解，这里拆开写：

npm install -g openclaw@latest
openclaw onboard --install-daemon

pnpm：

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

bun：

bun add -g openclaw@latest
openclaw onboard --install-daemon

6.3 -> 验证安装

openclaw --version
openclaw doctor
openclaw gateway status

如果你安装时选择了 daemon，Gateway 应该已经作为后台服务运行。macOS 通常是 LaunchAgent，Linux / WSL2 通常是 systemd user service，Windows 可能是 Scheduled Task 或 Startup-folder fallback。

7 -> 第一次启动和 Dashboard

如果你还没有初始化：

openclaw onboard --install-daemon

之后打开 Dashboard：

openclaw dashboard

官方文档给出的本地默认地址是：

http://127.0.0.1:18789/

Dashboard 或 Control UI 适合做三件事：

检查 Gateway 是否在线。
测试与 Agent 的基础对话。
查看或调整部分配置、会话和状态。

如果 Gateway 起不来，可以用前台调试模式：

openclaw gateway stop
openclaw gateway --port 18789 --verbose

这时你能直接看到日志，更容易定位是 Node、PATH、配置、端口占用还是权限问题。

8 -> 理解 OpenClaw 的目录结构

OpenClaw 核心有两个层次：

8.1 -> ~/.openclaw/

这是 OpenClaw 状态、配置、凭据和会话所在的位置。官方文档提醒，下面这些内容不应该提交到 workspace repo：

~/.openclaw/openclaw.json
模型 auth profiles
channel/provider credentials
session transcripts
managed skills
per-agent Codex runtime account、plugins、skills、native thread state

这里很可能包含敏感信息，应该当成私有系统目录处理。

8.2 -> Agent workspace

默认是：

~/.openclaw/workspace

官方文档把 workspace 定义为 Agent 的 home：文件工具和 workspace context 的默认工作目录。它应该被当成私有记忆。

注意：workspace 是默认 cwd，不等于天然沙箱。除非启用 sandbox，否则工具仍然可能通过绝对路径访问主机其他位置。

9 -> 写好 Agent 的工作区文件

一个好用的 OpenClaw Agent，不是只靠模型强，而是靠稳定的上下文和边界。以下文件建议认真写。

9.1 -> AGENTS.md

这是操作规则和长期工作习惯。可以写：

Agent 的核心任务范围。
处理任务的默认流程。
哪些动作必须请示。
哪些信息不能外发。
如何记录记忆。
如何处理不确定性。

示例：

# Operating Rules

- You are my private work assistant.
- Before sending messages externally, draft first and wait for approval.
- Never expose API keys, private files, customer data, or credentials.
- For file edits, keep changes small and verify them.
- When a task is ambiguous, ask one concise clarifying question.
- Write durable preferences and decisions into MEMORY.md only after they are confirmed.

9.2 -> SOUL.md

这是人格、语气和边界。不要写成玄学设定，应该写成可执行的行为风格。

示例：

# Persona

- Be direct, calm, and pragmatic.
- Prefer concise plans and executable next steps.
- Do not overpromise.
- Separate facts, assumptions, and recommendations.

9.3 -> USER.md

这是用户资料和偏好。适合写：

你是谁。
你的工作重点。
你希望如何被称呼。
你偏好的输出语言和格式。
你对风险、速度、细节程度的偏好。

不要写身份证、真实密码、API key 或客户隐私。

9.4 -> TOOLS.md

这是本地工具约定，不控制工具是否存在，只告诉 Agent 如何使用你已有的工具。

示例：

# Local Tool Conventions

- Prefer read-only inspection before edits.
- Prefer official docs for fast-moving installation instructions.
- For scripts, show the command and expected outcome before suggesting execution.
- For risky operations, explain rollback steps.

9.5 -> MEMORY.md 与 memory/YYYY-MM-DD.md

官方 Memory 文档说明，OpenClaw 通过在 workspace 写 Markdown 文件来记住东西，没有隐藏状态。常见分工是：

MEMORY.md：长期稳定记忆，举个例子偏好、事实、长期决策、短摘要。
memory/YYYY-MM-DD.md：当天或近期工作层，适合记录详细日志、观察、会话摘要。

实践建议：

MEMORY.md 要短，放稳定结论，不放原始对话大段文本。
每日文件可以详细一点，供搜索和回溯。
涉及“可以自动执行”的记忆要写清楚条件和边界，比如“只有在我明确说确认后才能外发”。
不要把密钥、客户原始数据、私密聊天原文直接写入记忆。

10 -> 配置 openclaw.json

OpenClaw 的可选配置文件位于：

~/.openclaw/openclaw.json

如果没有配置，OpenClaw 会使用安全默认值。随着你接入通道、模型、工具和安全策略，就会逐步需要改它。

官方配置文档强调，OpenClaw 会严格校验配置。未知 key、类型错误、非法值可能导致 Gateway 拒绝启动。失败时可以用：

openclaw doctor
openclaw doctor --fix

10.1 -> 最小配置思路

官方 Agent runtime 文档提到，最小配置至少关注：

agents.defaults.workspace
channels.whatsapp.allowFrom，如果你启用 WhatsApp，强烈建议限制来源

示例仅作结构演示，里面的手机号必须替换为你自己的授权号码：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+10000000000"],
      groups: {
        "*": { requireMention: true }
      }
    }
  },
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

更推荐用 CLI 修改配置，减少手工编辑 JSON5 时的语法错误：

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.workspace "~/.openclaw/workspace"
openclaw doctor
openclaw gateway restart

11 -> 配置模型

OpenClaw 的模型引用通常采用：

provider/model

举个例子：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"]
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" }
      }
    }
  }
}

实际选择模型时建议按任务来：

日常助理：选择速度、成本、可靠性平衡的模型。
代码修改：选择工具调用和长上下文表现更稳定的模型。
高风险分析：选择推理更强的模型，并保留人工审查。
图像、音频、浏览器操作：确认对应工具和模型能力支持。

模型密钥不要写进可备份的 workspace。使用 OpenClaw 的 auth/profile、凭据管理、环境变量或系统密钥管理方案。

12 -> 连接消息通道

OpenClaw 的价值之一是多通道：Telegram、WhatsApp、Slack、Discord、Google Chat、Signal、iMessage、WebChat 等入口可以通过 Gateway 进入 Agent。

但接通道前要先问三个问题：

1. 谁可以给这个 Agent 发消息？
2. 这个 Agent 接到消息后能使用哪些工具？
3. 如果消息来自群聊或外部用户，是否有 prompt injection 风险？

12.1 -> DM 策略

官方配置文档列出常见 DM policy：

pairing：未知发送者收到一次性 pairing code，需要批准。
allowlist：只允许 allowFrom 或已配对 allow store 中的发送者。
open：允许所有 inbound DM，需要显式 allowFrom: ["*"]。
disabled：忽略所有 DM。

建议：

个人使用先用 pairing。
生产或工作场景优先 allowlist。
不要为了省事把外部通道设成 open。
群聊默认要求 mention，避免 Agent 被无关消息持续触发。

12.2 -> 群聊 mention gating

示例结构：

{
  messages: {
    visibleReplies: "automatic",
    groupChat: {
      visibleReplies: "message_tool",
      unmentionedInbound: "room_event"
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      }
    ]
  },
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

这类配置的意义是：群聊里的信息可以作为上下文，但可见回复要更克制，避免 Agent 在共享房间里自动乱说话。

13 -> 权限和安全：别把“能跑”误认为“能安全跑”

OpenClaw 的风险来自三件事叠加：

1. 外部消息入口可能是不可信输入。
2. Agent 会根据自然语言理解任务。
3. 工具可能能读写文件、执行命令、调用浏览器或访问外部系统。

于是安全不是附加项，而是搭建流程的一部分。

13.1 -> tools.exec.mode

官方 Permission modes 文档给出几种模式：

deny：完全禁止 host exec。
allowlist：只允许 allowlist 命令。
ask：allowlist 命中直接运行，miss 时请人批准。
auto：allowlist 命中直接运行，miss 时先自动审查，必要时再请人批准。
full：host exec 无提示运行。

建议：

第一次搭建：auto 或 ask。
不需要命令执行的 Agent：deny。
固定工作流 Agent：allowlist。
不要在外部通道、群聊、共享环境里使用 full。
如果你确实使用 full，要明确这是信任单人、本机、可控边界下的选择。

示例：

openclaw config set tools.exec.mode auto
openclaw approvals get
openclaw gateway restart
openclaw exec-policy show

13.2 -> Sandbox

官方 Agent workspace 文档提醒：workspace 是 cwd，不是硬沙箱。要隔离文件系统和工具权限，需要启用 sandbox。

适合启用 sandbox 的场景：

群聊触发的会话。
外部账号可能发消息的通道。
测试第三方 Skills 或插件。
Agent 需要运行未知代码。
需要把 main 私人会话和其他会话隔开。

一个常见策略是：main 私人会话保留较高权限，non-main 会话放入 sandbox。

13.3 -> Skills 也要做最小权限

OpenClaw Skills 是带 YAML frontmatter 的 Markdown 指令文件，告诉 Agent 何时、如何使用工具。它们可以来自 workspace、project agent、personal agent、managed/local、bundled 或 extra dirs。

加载优先级大致是：

1. /skills
2. /.agents/skills
3. ~/.agents/skills
4. ~/.openclaw/skills
5. bundled skills
6. extra dirs 和 plugin skills

建议：

工作区专用能力放在 /skills。
多 Agent 共用能力放在 ~/.agents/skills 或 ~/.openclaw/skills。
第三方 Skills 先阅读源码和说明，不要默认信任。
对不同 Agent 使用 agents.defaults.skills 或 agents.list[].skills 限定可用技能。

示例：

{
  agents: {
    defaults: {
      skills: ["github", "docs-search"]
    },
    list: [
      { id: "writer", skills: ["docs-search"] },
      { id: "locked-down", skills: [] }
    ]
  }
}

13.4 -> 安全审计

每次扩大入口、开放远程访问、加插件、加工具或改 exec 策略后，都应该跑：

openclaw security audit
openclaw security audit --deep
openclaw security audit --json

如果你愿意让它做有限安全修复：

openclaw security audit --fix

官方文档说明，--fix 是窄范围修复，比如收紧开放群组策略、恢复敏感日志脱敏、修正状态和配置文件权限等。它不是万能安全工具。

14 -> 设计一个真正好用的 Agent

一个 OpenClaw Agent 的质量，核心取决于四个层面。

14.1 -> 身份清楚

不要只写“你是一个助手”。要写：

你服务谁。
你主要做什么。
你不做什么。
你遇到冲突时听哪条规则。
什么时候必须请人确认。

14.2 -> 工作流清楚

举个例子一个“个人工作推进 Agent”可以这样定义：

1. 收到任务后先判断是否需要澄清。
2. 简单任务直接给结果。
3. 需要文件或外部动作时先列计划。
4. 高风险动作必须等待确认。
5. 完成后写一条简短记忆或任务日志。

14.3 -> 记忆分层

不要把所有东西都塞进 MEMORY.md。建议：

稳定偏好和长期事实进 MEMORY.md。
当天讨论、过程记录、试验结果进 memory/YYYY-MM-DD.md。
具体项目资料放项目目录或专门知识库。
敏感原文只保留链接、摘要或脱敏版本。

14.4 -> 权限渐进

最初只允许读信息和回答问题。之后再加：

1. 文件读写。
2. 命令执行。
3. 浏览器。
4. 消息发送。
5. 定时任务。
6. 外部系统写入。

每加一层，都要问：如果 Agent 被错误指令或恶意消息诱导，最坏会发生什么？

15 -> 三个可落地模板

15.1 -> 模板 A：个人代码助理

适合：自己在电脑上随时给 Codex / Claude / OpenClaw 发任务。

建议配置：

通道：Control UI + Telegram pairing。
workspace：私有 git repo 备份。
exec：auto 或 ask。
sandbox：non-main 开启。
skills：github、docs-search、local-project。
规则：代码改动前先读上下文，危险命令必须确认。

边界：

不接陌生人消息。
不自动 push、merge、deploy。
不存 API key 到 workspace。

15.2 -> 模板 B：团队内部知识助理

适合：内部文档检索、会议纪要、流程问答。

建议配置：

通道：Slack / Teams allowlist。
exec：deny 或 allowlist。
skills：docs-search、meeting-notes。
记忆：只写确认后的团队口径，不写敏感原始记录。
群聊：requireMention + visibleReplies 克制。

边界：

不接生产数据库。
不给未经授权用户返回内部资料。
不自动代表团队对外回复。

15.3 -> 模板 C：工作流推进助理

适合：个人日程、任务追踪、草稿生成、提醒、周报。

建议配置：

通道：个人 Telegram / WhatsApp allowlist。
exec：ask。
skills：calendar、mail-draft、task-board。
规则：外发前必须确认。
heartbeat：每天检查未完成任务，但只推 1 到 3 个需要人拍板的事项。

边界：

可以起草，不自动发送重要消息。
可以建议，不自动承诺资源或时间。
可以整理记忆，不写入未经确认的推测。

16 -> 常见问题和排障

16.1 -> openclaw 命令找不到

大概率是 PATH 问题。

检查：

node -v
npm prefix -g
echo "$PATH"

Windows PowerShell 可检查：

node -v
npm prefix -g
$env:Path

处理方式：把 npm global bin 加入 PATH，或者重新打开终端。

16.2 -> Gateway 起不来

先跑：

openclaw doctor
openclaw gateway status

如果是配置校验失败：

openclaw doctor --fix

如果要看详细日志：

openclaw gateway stop
openclaw gateway --port 18789 --verbose

16.3 -> Dashboard 打不开

检查：

Gateway 是否启动。
端口 18789 是否被占用。
是否访问本机 127.0.0.1。
是否误把 Gateway 绑定到了其他地址。

16.4 -> Agent 回复不符合预期

优先检查：

AGENTS.md 是否写得太空。
SOUL.md 是否和任务要求冲突。
MEMORY.md 是否堆了过多旧信息。
通道是否进了错误 session。
模型是否被切换到较弱 fallback。

16.5 -> Agent 能力太强，心里不踏实

收紧顺序：

1. 把外部通道改成 allowlist 或 disabled。
2. 群聊要求 mention。
3. tools.exec.mode 从 full 改成 auto、ask、allowlist 或 deny。
4. 给 non-main 会话启用 sandbox。
5. 限制 skills。
6. 跑 openclaw security audit --deep。

17 -> 上线前检查清单

基础运行：

openclaw --version 正常。
openclaw doctor 无关键错误。
openclaw gateway status 显示 Gateway 正常。
openclaw dashboard 能打开。

工作区：

AGENTS.md 写清楚任务范围和确认边界。
SOUL.md 写清楚语气、人格和禁止事项。
USER.md 不包含敏感隐私。
MEMORY.md 只放稳定长期事实。
memory/*.md 不保存未脱敏客户数据。

模型和通道：

primary model 和 fallback 可用。
外部 DM 使用 pairing 或 allowlist。
群聊 requireMention。
没有把陌生人入口设成 open。

工具和安全：

tools.exec.mode 不是无意识的 full。
非 main 或外部通道会话有 sandbox 策略。
skills 按 Agent 限定。
openclaw security audit 已运行。
远程访问没有暴露无认证控制面。

运维：

workspace 有私有备份。
~/.openclaw/ 不进 git。
配置改动前有备份。
知道如何 stop、restart、查看 logs。

18 -> 最佳实践总结

OpenClaw Agent 搭建的关键，不是把所有能力一次性打开，而是建立一个渐进式系统：

Gateway 负责统一入口和会话。
Workspace 负责规则、身份和长期上下文。
Memory 负责把经验沉淀成可复用资产。
Skills 负责把工具能力变成可调用流程。
Permission、allowlist、sandbox 和 audit 负责把风险压住。

真正成熟的 OpenClaw Agent 应该像一个可控的工作伙伴：它知道你是谁，知道项目边界，知道什么时候能自己推进，什么时候必须停下来请你判断，也知道哪些事情永远不能做。

如果只追求“它能执行命令”，很容易得到一个高风险自动化入口。
如果按“可运行、可控、可审计、可回滚”的顺序搭建，它才会变成长期有用的个人 AI 基础设施。

感谢各位大佬支持！！！

互三啦！！！

这篇笔记就先到这里，后面用到新的思路或者发现有问题再补充。

分享：OpenClaw Agent 搭建全流程：从本机自托管到可用、可控、可审计的个人 AI 助手

这篇目录

1 -> 先说结论

2 -> OpenClaw 到底是什么

3 -> 适合谁，不适合谁

4 -> 整体搭建路线

4.1 -> 阶段 1：安装 OpenClaw 并启动 Gateway

4.2 -> 阶段 2：建立 Agent 工作区

4.3 -> 阶段 3：配置模型和通道

4.4 -> 阶段 4：开放工具、Skills 和自动化

4.5 -> 阶段 5：做审计、日志、备份和回滚

5 -> 准备环境

5.1 -> 检查 Node

6 -> 安装 OpenClaw

6.1 -> 推荐方式：官方安装脚本

6.2 -> 已经自己管理 Node 时：npm 安装

6.3 -> 验证安装

7 -> 第一次启动和 Dashboard

8 -> 理解 OpenClaw 的目录结构

8.1 -> ~/.openclaw/

8.2 -> Agent workspace

9 -> 写好 Agent 的工作区文件

9.1 -> AGENTS.md

9.2 -> SOUL.md

9.3 -> USER.md

9.4 -> TOOLS.md

9.5 -> MEMORY.md 与 memory/YYYY-MM-DD.md

10 -> 配置 openclaw.json

10.1 -> 最小配置思路

11 -> 配置模型

12 -> 连接消息通道

12.1 -> DM 策略

12.2 -> 群聊 mention gating

13 -> 权限和安全：别把“能跑”误认为“能安全跑”

13.1 -> tools.exec.mode

13.2 -> Sandbox

13.3 -> Skills 也要做最小权限

13.4 -> 安全审计

14 -> 设计一个真正好用的 Agent

14.1 -> 身份清楚

14.2 -> 工作流清楚

14.3 -> 记忆分层

14.4 -> 权限渐进

15 -> 三个可落地模板

15.1 -> 模板 A：个人代码助理

15.2 -> 模板 B：团队内部知识助理

15.3 -> 模板 C：工作流推进助理

16 -> 常见问题和排障

16.1 -> openclaw 命令找不到

16.2 -> Gateway 起不来

16.3 -> Dashboard 打不开

16.4 -> Agent 回复不符合预期

16.5 -> Agent 能力太强，心里不踏实

17 -> 上线前检查清单

18 -> 最佳实践总结

评论 (0)