1. 先搞清楚 OpenClawan 到底在装什么OpenClawan 是一套跑在你自己设备上的个人 AI 助手网关核心是一个叫 Gateway 的本地服务默认监听ws://127.0.0.1:18789。它把通讯渠道Telegram、Slack、Discord、WebChat 等、AI 智能体Agent、命令行工具、浏览器控制串在一起你通过已经习惯的聊天窗口就能指挥它干活。适合谁适合想把 AI 助手私有化、又不想被某个云端平台绑死的开发者尤其是需要多智能体分工一个写代码、一个查资料、一个管日程的人。很多人第一次装 OpenClawan 会卡在三个地方Node 版本不够、Gateway 起不来、配置文件格式写错。这篇安装指南按「架构讲解 → 安装 → 配置对话终端 → 多智能体 → 技能安装 → 故障排除」的顺序走一遍每一步都给可复制的命令和配置骨架。我试过在 macOS 和 WSL2 上各跑一遍下面这套流程基本能一次过。先看架构理解了后面配置就不容易懵WhatsApp / Telegram / Slack / Discord / WebChat │ ▼ ┌───────────────────────┐ │ Gateway (控制平面) │ │ ws://127.0.0.1:18789 │ └───────────┬───────────┘ │ ┌───────────┼───────────┬──────────────┐ ▼ ▼ ▼ ▼ AI Agent CLI 命令行 WebChat 页面 浏览器控制(CDP)Gateway 是唯一的核心所有渠道消息都先到它这里再由它分发给对应的 Agent。Workspace 是 Agent 的工作目录它读上下文、存记忆、执行工具操作都在这里发生。记住这两点后面openclaw.json里为什么有agents和channels两块就清楚了。2. 安装前置Node 版本与 TaoToken 接入准备系统要求很硬Node.js ≥ 22这是必须的低于这个版本 Gateway 会直接报错退出。操作系统支持 macOS、Linux、Windows走 WSL2。包管理器用 npm、pnpm 或 bun 都行。安装命令三选一# macOS / Linux 一键脚本 curl -fsSL https://openclaw.ai/install.sh | bash # Windows PowerShell iwr -useb https://openclaw.ai/install.ps1 | iex # npm 全局安装 npm install -g openclawlatest装完跑引导它会帮你生成初始配置并注册系统服务# 完整安装引导 安装系统服务 openclaw onboard --install-daemon # 只跑配置引导 openclaw onboard检查是否装好openclaw gateway status openclaw dashboard模型接入这块OpenClawan 本身不绑定某一家模型服务你可以把模型请求指向兼容 OpenAI 协议的服务。TaoToken 提供的就是这种兼容接口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先在控制台建一个 Key后面填进配置里模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 只存在本地~/.openclaw/credentials/目录别提交到 Git也别贴进聊天记录。3. 可复制配置openclaw.json 骨架与对话终端核心配置文件是~/.openclaw/openclaw.json用 JSON5 格式支持注释和尾随逗号这点比纯 JSON 友好。先给一份最小可跑骨架{ agents: { defaults: { workspace: ~/.openclaw/workspace, model: { primary: anthropic/claude-sonnet-4-5, fallbacks: [openai/gpt-5.2] }, heartbeat: { every: 30m, target: last } } }, channels: { telegram: { enabled: true, botToken: 123456:ABC..., dmPolicy: pairing, allowFrom: [tg:123456789] } }, session: { dmScope: per-channel-peer, reset: { mode: daily, atHour: 4, idleMinutes: 120 } } }Workspace 目录结构长这样建议先建好~/.openclaw/ ├── openclaw.json # 主配置 ├── workspace/ # 默认工作空间 │ ├── AGENTS.md # 操作指令和记忆 │ ├── SOUL.md # 人格、边界、语气 │ ├── TOOLS.md # 工具使用笔记 │ ├── USER.md # 用户信息 │ ├── MEMORY.md # 长期记忆仅主会话加载 │ └── skills/ # 工作空间级技能 ├── agents/ # 多智能体会话存储 ├── skills/ # 全局技能 └── credentials/ # 凭证存储对话终端Channels的 DM 安全策略必须选对这是最容易出事的地方策略说明适用场景pairing未知发送者获得配对码需主人批准默认最安全allowlist仅允许列表中的发送者已知联系人open允许所有入站 DM公开机器人disabled忽略所有 DM仅群组使用Telegram 配置示例streaming设成partial可以让回复边生成边显示{ channels: { telegram: { enabled: true, botToken: your-bot-token, dmPolicy: pairing, allowFrom: [tg:123456789], streaming: partial } } }4. 多智能体配置与技能安装多智能体是 OpenClawan 比较有意思的部分你可以给不同任务配不同的 Agent各自有独立 workspace互不干扰{ agents: { defaults: { workspace: ~/.openclaw/workspace }, list: [ { id: main, description: 通用助手 }, { id: coder, workspace: ~/.openclaw/workspace-coder, description: 编程专家 } ] } }技能系统用来扩展能力通过 ClawHub CLI 从 clawhub.com 安装。先装 CLInpm install -g clawhub搜索和安装# 搜索 clawhub search postgres backups clawhub search image generation # 安装最新版 clawhub install baoyu-image-gen # 安装指定版本 clawhub install baoyu-image-gen --version 1.2.3技能管理命令对照命令说明示例clawhub list列出已安装技能查看当前工作空间所有技能clawhub update更新指定技能clawhub update baoyu-image-genclawhub update --all批量更新更新所有已安装技能clawhub update --force强制更新解决版本冲突时用常用推荐技能技能名功能安装命令baoyu-image-genAI 图像生成clawhub install baoyu-image-genweather天气查询和预报clawhub install weathergithubGitHub 操作clawhub install githubvideo-frames视频帧提取和剪辑clawhub install video-framesfind-skills帮助发现和安装技能clawhub install find-skills技能本质是一个文件夹里面SKILL.md定义能力和使用说明其他文件是脚本和配置。装完后 OpenClawan 会自动识别任务触发时自动调用不用额外配置。想发布自己的技能clawhub login clawhub publish ./my-skill \ --slug my-skill \ --name My Skill \ --version 1.0.0 \ --changelog Initial release5. 验证请求与成功结果配置写完别急着用先跑一轮验证。启动 Gateway# 前台运行适合调试 openclaw gateway --port 18789 --verbose # 守护进程后台运行 openclaw gateway start打开控制面板openclaw dashboard # 或浏览器直接访问 http://127.0.0.1:18789发送测试消息openclaw message send --to 15555550123 --message Hello from OpenClaw和智能体对话openclaw agent --message 帮我总结今天的会议 --thinking high成功的话你会看到Gateway 状态显示 runningdashboard 页面能打开测试消息出现在目标渠道agent 命令返回一段模型生成的文本。如果模型请求走的是 TaoToken 的兼容接口返回内容正常就说明 Key 和端点都通了。想单独验证模型连通性可以直接用模型对话页面发一条https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite常用 CLI 命令清单建议存一份# Gateway 管理 openclaw gateway status openclaw gateway start openclaw gateway stop openclaw gateway restart # 配置管理 openclaw onboard openclaw config get agents.defaults.workspace openclaw config set agents.defaults.model.primary openai/gpt-5.2 # 诊断工具 openclaw doctor openclaw doctor --fix openclaw logs --follow6. 本篇常见错排查Config validation failed配置格式错误。JSON5 虽然宽松但括号和引号还是要配对。跑openclaw doctor会指出具体哪一行。改完重启 Gateway。UnauthorizedAPI Key 无效。检查credentials/目录下的凭证确认 Key 没写错、没过期。如果用的是 TaoToken 的 Key去控制台核对一下https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewriteSession not found会话已过期。发送/new重置或者检查session.reset配置里的idleMinutes是不是设太短。Gateway 起不来端口被占换端口openclaw gateway --port 18790或者先openclaw gateway stop再启动。技能装了但没生效确认技能装在正确的 workspace 下clawhub list能看到。有些技能需要额外配置 API Key看SKILL.md里的说明。Node 版本报错node -v确认 ≥ 22低了就升级。WSL2 用户注意别装成 Windows 侧的 Node。安全上再强调一句永远不要在未经保护的情况下公开 DM用dmPolicy: pairing或allowlist多用户环境加沙箱{ agents: { defaults: { sandbox: { mode: non-main, scope: agent } } } }长期跑编码类任务或者多智能体协作可以考虑 Coding Plan 来管理模型调用额度https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入细节和参数说明都在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite排障时优先跑openclaw doctor --fix大部分配置问题它能自动修。日志用openclaw logs --follow实时看报错信息通常很直白。