文章目录1 - 先说结论2 - OpenClaw 到底是什么3 - 适合谁不适合谁4 - 整体搭建路线4.1 - 阶段 1安装 OpenClaw 并启动 Gateway4.2 - 阶段 2建立 Agent 工作区4.3 - 阶段 3配置模型和通道4.4 - 阶段 4开放工具、Skills 和自动化4.5 - 阶段 5做审计、日志、备份和回滚5 - 准备环境5.1 - 检查 Node6 - 安装 OpenClaw6.1 - 推荐方式官方安装脚本6.2 - 已经自己管理 Node 时npm 安装6.3 - 验证安装7 - 第一次启动和 Dashboard8 - 理解 OpenClaw 的目录结构8.1 - ~/.openclaw/8.2 - Agent workspace9 - 写好 Agent 的工作区文件9.1 - AGENTS.md9.2 - SOUL.md9.3 - USER.md9.4 - TOOLS.md9.5 - MEMORY.md 与 memory/YYYY-MM-DD.md10 - 配置 openclaw.json10.1 - 最小配置思路11 - 配置模型12 - 连接消息通道12.1 - DM 策略12.2 - 群聊 mention gating13 - 权限和安全别把“能跑”误认为“能安全跑”13.1 - tools.exec.mode13.2 - Sandbox13.3 - Skills 也要做最小权限13.4 - 安全审计14 - 设计一个真正好用的 Agent14.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 - 最佳实践总结1 - 先说结论OpenClaw 的核心不是“再装一个聊天机器人”而是把一个自托管的 Gateway 放在你自己的电脑或服务器上让它连接多个消息入口、一个或多个 Agent、模型供应商、工具权限、工作区记忆和安全策略。如果把 OpenClaw Agent 搭好它可以像一个随时在线的个人执行入口你从 Telegram、WhatsApp、Slack、WebChat 或 Control UI 发消息Gateway 负责识别来源、选择会话、装配上下文、调用模型和工具再把结果送回原来的通道。但也正因为它能连接真实账号、真实文件和真实命令搭建顺序不能只追求“跑起来”。更合理的顺序是先让 Gateway 稳定运行。再把 Agent 的工作区、记忆和边界写清楚。然后接模型和消息通道。最后逐步开放工具、Skills 和自动化。每次扩大权限前都做审计和回滚准备。2 - OpenClaw 到底是什么按照官方文档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。控制权更强但运维、安全和权限边界也由你负责。GatewayOpenClaw 不是单一聊天窗口。Gateway 更像中枢负责处理通道、会话、模型、工具、节点、Dashboard、路由等问题。Agent-nativeOpenClaw 内置 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--versionopenclaw doctor openclaw gateway status openclaw dashboard4.2 - 阶段 2建立 Agent 工作区目标明确这个 Agent 是谁、听谁的、能做什么、不能做什么、怎么记录长期记忆。核心文件AGENTS.mdSOUL.mdUSER.mdIDENTITY.mdTOOLS.mdHEARTBEAT.mdMEMORY.mdmemory/YYYY-MM-DD.md4.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 doctoropenclaw security auditopenclaw logs私有备份 workspace不提交密钥和会话凭据。5 - 准备环境官方安装文档给出的系统要求是Node 22.19、23.11 或 24其中 Node 24 是默认目标。macOS、Linux 或 Windows。如果从源码构建需要pnpm。实践建议新手优先用官方 installer script让它处理 Node 和初始化。Windows 用户可以选择 PowerShell CLI 安装也可以先看 Windows Hub companion app。如果你未来要接高权限工具建议使用单独的系统用户、单独机器、WSL2、Docker 或 VPS至少不要和日常浏览器、私人文件混在同一个高权限环境里。不要在公司生产电脑上直接试验不受控工具权限先在测试环境搭。5.1 - 检查 Nodenode-vnpm-v如果node -v不满足版本要求优先按官方安装器走或者用你熟悉的 Node 管理方式升级。6 - 安装 OpenClaw6.1 - 推荐方式官方安装脚本macOS / Linux / WSL2curl-fsSLhttps://openclaw.ai/install.sh|bashWindows PowerShelliwr-useb https://openclaw.ai/install.ps1|iex如果只想安装不立即进入 onboardingmacOS / Linux / WSL2curl-fsSLhttps://openclaw.ai/install.sh|bash-s-- --no-onboardWindows PowerShell([scriptblock]::Create((iwr-useb https://openclaw.ai/install.ps1)))-NoOnboard6.2 - 已经自己管理 Node 时npm 安装官方文档也提供 npm、pnpm、bun 等安装方式。为了避免命令粘在一行导致误解这里拆开写npminstall-gopenclawlatest openclaw onboard --install-daemonpnpmpnpmadd-gopenclawlatestpnpmapprove-builds-gopenclaw onboard --install-daemonbunbunadd-gopenclawlatest openclaw onboard --install-daemon6.3 - 验证安装openclaw--versionopenclaw doctor openclaw gateway status如果你安装时选择了 daemonGateway 应该已经作为后台服务运行。macOS 通常是 LaunchAgentLinux / WSL2 通常是 systemd user serviceWindows 可能是 Scheduled Task 或 Startup-folder fallback。7 - 第一次启动和 Dashboard如果你还没有初始化openclaw onboard --install-daemon然后打开 Dashboardopenclaw dashboard官方文档给出的本地默认地址是http://127.0.0.1:18789/Dashboard 或 Control UI 适合做三件事检查 Gateway 是否在线。测试与 Agent 的基础对话。查看或调整部分配置、会话和状态。如果 Gateway 起不来可以用前台调试模式openclaw gateway stop openclaw gateway--port18789--verbose这时你能直接看到日志更容易定位是 Node、PATH、配置、端口占用还是权限问题。8 - 理解 OpenClaw 的目录结构OpenClaw 主要有两个层次8.1 -~/.openclaw/这是 OpenClaw 状态、配置、凭据和会话所在的位置。官方文档提醒下面这些内容不应该提交到 workspace repo~/.openclaw/openclaw.json模型 auth profileschannel/provider credentialssession transcriptsmanaged skillsper-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.jsonOpenClaw 的可选配置文件位于~/.openclaw/openclaw.json如果没有配置OpenClaw 会使用安全默认值。随着你接入通道、模型、工具和安全策略就会逐步需要改它。官方配置文档强调OpenClaw 会严格校验配置。未知 key、类型错误、非法值可能导致 Gateway 拒绝启动。失败时可以用openclaw doctor openclaw doctor--fix10.1 - 最小配置思路官方 Agent runtime 文档提到最小配置至少关注agents.defaults.workspacechannels.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 configsetagents.defaults.workspace~/.openclaw/workspaceopenclaw doctor openclaw gateway restart11 - 配置模型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。但接通道前要先问三个问题谁可以给这个 Agent 发消息这个 Agent 接到消息后能使用哪些工具如果消息来自群聊或外部用户是否有 prompt injection 风险12.1 - DM 策略官方配置文档列出常见 DM policypairing未知发送者收到一次性 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 的风险来自三件事叠加外部消息入口可能是不可信输入。Agent 会根据自然语言理解任务。工具可能能读写文件、执行命令、调用浏览器或访问外部系统。所以安全不是附加项而是搭建流程的一部分。13.1 -tools.exec.mode官方 Permission modes 文档给出几种模式deny完全禁止 host exec。allowlist只允许 allowlist 命令。askallowlist 命中直接运行miss 时请人批准。autoallowlist 命中直接运行miss 时先自动审查必要时再请人批准。fullhost exec 无提示运行。建议第一次搭建auto或ask。不需要命令执行的 Agentdeny。固定工作流 Agentallowlist。不要在外部通道、群聊、共享环境里使用full。如果你确实使用full要明确这是信任单人、本机、可控边界下的选择。示例openclaw configsettools.exec.mode auto openclaw approvals get openclaw gateway restart openclaw exec-policy show13.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。加载优先级大致是workspace/skillsworkspace/.agents/skills~/.agents/skills~/.openclaw/skillsbundled skillsextra dirs 和 plugin skills建议工作区专用能力放在workspace/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--deepopenclaw security audit--json如果你愿意让它做有限安全修复openclaw security audit--fix官方文档说明--fix是窄范围修复比如收紧开放群组策略、恢复敏感日志脱敏、修正状态和配置文件权限等。它不是万能安全工具。14 - 设计一个真正好用的 Agent一个 OpenClaw Agent 的质量主要取决于四个层面。14.1 - 身份清楚不要只写“你是一个助手”。要写你服务谁。你主要做什么。你不做什么。你遇到冲突时听哪条规则。什么时候必须请人确认。14.2 - 工作流清楚例如一个“个人工作推进 Agent”可以这样定义收到任务后先判断是否需要澄清。简单任务直接给结果。需要文件或外部动作时先列计划。高风险动作必须等待确认。完成后写一条简短记忆或任务日志。14.3 - 记忆分层不要把所有东西都塞进MEMORY.md。建议稳定偏好和长期事实进MEMORY.md。当天讨论、过程记录、试验结果进memory/YYYY-MM-DD.md。具体项目资料放项目目录或专门知识库。敏感原文只保留链接、摘要或脱敏版本。14.4 - 权限渐进最初只允许读信息和回答问题。之后再加文件读写。命令执行。浏览器。消息发送。定时任务。外部系统写入。每加一层都要问如果 Agent 被错误指令或恶意消息诱导最坏会发生什么15 - 三个可落地模板15.1 - 模板 A个人代码助理适合自己在电脑上随时给 Codex / Claude / OpenClaw 发任务。建议配置通道Control UI Telegram pairing。workspace私有 git repo 备份。execauto或ask。sandboxnon-main 开启。skillsgithub、docs-search、local-project。规则代码改动前先读上下文危险命令必须确认。边界不接陌生人消息。不自动 push、merge、deploy。不存 API key 到 workspace。15.2 - 模板 B团队内部知识助理适合内部文档检索、会议纪要、流程问答。建议配置通道Slack / Teams allowlist。execdeny或allowlist。skillsdocs-search、meeting-notes。记忆只写确认后的团队口径不写敏感原始记录。群聊requireMention visibleReplies 克制。边界不接生产数据库。不给未经授权用户返回内部资料。不自动代表团队对外回复。15.3 - 模板 C工作流推进助理适合个人日程、任务追踪、草稿生成、提醒、周报。建议配置通道个人 Telegram / WhatsApp allowlist。execask。skillscalendar、mail-draft、task-board。规则外发前必须确认。heartbeat每天检查未完成任务但只推 1 到 3 个需要人拍板的事项。边界可以起草不自动发送重要消息。可以建议不自动承诺资源或时间。可以整理记忆不写入未经确认的推测。16 - 常见问题和排障16.1 -openclaw命令找不到大概率是 PATH 问题。检查node-vnpmprefix-gecho$PATHWindows 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--port18789--verbose16.3 - Dashboard 打不开检查Gateway 是否启动。端口18789是否被占用。是否访问本机127.0.0.1。是否误把 Gateway 绑定到了其他地址。16.4 - Agent 回复不符合预期优先检查AGENTS.md是否写得太空。SOUL.md是否和任务要求冲突。MEMORY.md是否堆了过多旧信息。通道是否进了错误 session。模型是否被切换到较弱 fallback。16.5 - Agent 能力太强心里不踏实收紧顺序把外部通道改成allowlist或disabled。群聊要求 mention。tools.exec.mode从full改成auto、ask、allowlist或deny。给 non-main 会话启用 sandbox。限制 skills。跑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 基础设施。感谢各位大佬支持互三啦