文章目录OpenClaw 使用教程目录一、简介1.1 什么是 OpenClaw1.2 适用场景二、环境准备2.1 系统要求2.2 检查环境三、安装与配置3.1 安装 OpenClaw3.2 快速配置向导3.3 手动配置3.3.1 创建配置文件3.3.2 环境变量配置3.4 启动 Gateway四、核心功能4.1 命令行交互4.2 交互式会话4.3 消息发送五、通道配置5.1 Telegram5.2 Discord5.3 Slack5.4 其他通道六、进阶使用6.1 技能Skills6.2 插件开发6.3 记忆系统6.4 自动化与 Cron6.5 Canvas 交互七、故障排查7.1 诊断工具7.2 常见问题7.3 日志调试八、最佳实践8.1 安全建议8.2 性能优化8.3 配置管理8.4 开发建议九、进阶场景9.1 多模型故障转移9.2 Docker 部署9.3 云平台部署十、资源与社区10.1 官方资源10.2 社区插件10.3 贡献指南十一、总结OpenClaw 使用教程目录简介环境准备安装与配置核心功能通道配置进阶使用故障排查最佳实践一、简介1.1 什么是 OpenClawOpenClaw 是一个开源的个人 AI 智能体框架运行在你的设备上可以通过自然语言控制计算机执行任务。核心特性本地优先数据不经过第三方服务器多通道支持WhatsApp、Telegram、Discord、Slack 等 20 平台高度可定制插件化架构支持自定义工具和技能安全可控显式权限管理危险操作需授权1.2 适用场景自动化日常任务文件管理、系统操作多平台消息统一处理个人知识库问答开发者工具集成隐私敏感的 AI 应用二、环境准备2.1 系统要求组件最低要求推荐配置操作系统macOS/Linux/Windows(WSL2)macOS 14 / Ubuntu 22.04Node.js2222.x LTS内存4GB8GB磁盘500MB2GB2.2 检查环境# 检查 Node 版本node--version# 应为 v22# 检查包管理器npm--version# 或pnpm--version安装 Node.js# macOS (Homebrew)brewinstallnode22# Ubuntu/Debiancurl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoapt-getinstall-ynodejs# Windows (WSL2)# 下载并安装 nvm Windows然后安装 Node 22三、安装与配置3.1 安装 OpenClaw方式一npm 全局安装推荐npminstall-gopenclawlatest# 或pnpmadd-gopenclawlatest方式二从源码安装gitclone https://github.com/openclaw/openclaw.gitcdopenclawpnpminstallpnpmbuildpnpmlink验证安装openclaw--version# 输出: 2026.3.9 (或当前版本)3.2 快速配置向导OpenClaw 提供交互式配置向导openclaw onboard --install-daemon向导会引导你完成✅ 模型提供商配置OpenAI、Anthropic 等✅ Gateway 网关设置✅ 消息通道配置✅ 安全策略设置✅ 守护进程安装3.3 手动配置3.3.1 创建配置文件配置文件位置~/.openclaw/openclaw.json{gateway:{mode:local,port:18789,bindAddress:127.0.0.1,auth:{token:your-random-token-here}},models:{default:openai,providers:{openai:{apiKey:${OPENAI_API_KEY},model:gpt-4o},anthropic:{apiKey:${ANTHROPIC_API_KEY},model:claude-sonnet-4-20250514}}},channels:{telegram:{enabled:true,botToken:${TELEGRAM_BOT_TOKEN},allowedUsers:[123456789]}}}3.3.2 环境变量配置创建~/.openclaw/.env# Gateway 认证生成随机令牌OPENCLAW_GATEWAY_TOKEN$(openssl rand-hex32)# 模型提供商密钥OPENAI_API_KEYsk-your-openai-keyANTHROPIC_API_KEYsk-ant-your-anthropic-key# 通道配置TELEGRAM_BOT_TOKENyour-telegram-bot-tokenDISCORD_BOT_TOKENyour-discord-bot-token生成安全的 Gateway Tokenopenssl rand-hex323.4 启动 Gateway前台运行openclaw gateway run--port18789--verbose后台运行守护进程# macOSopenclaw gateway run--daemon# Linux (systemd)openclaw gateway install-service systemctl--userstart openclaw-gateway systemctl--userenableopenclaw-gateway验证 Gateway 状态openclaw status四、核心功能4.1 命令行交互发送消息# 简单查询openclaw agent--message今天天气如何# 高推理模式复杂任务openclaw agent--message分析这个项目的架构--thinkinghigh# 指定输出通道openclaw agent--messageHello--outputtelegram工具调用# 文件操作openclaw agent--message列出当前目录的文件# 网页搜索openclaw agent--message搜索 OpenClaw 最新版本# 系统命令openclaw agent--message检查磁盘使用情况4.2 交互式会话# 启动交互式会话openclaw chat# 在会话中你好帮我创建一个待办事项列表总结今天的对话/exit# 退出4.3 消息发送# 发送到特定通道openclaw message send--to1234567890--messageHello from OpenClaw# 发送文件openclaw message send--touser-id--file./document.pdf# 发送到群组openclaw message send--tochat-id--message群组消息五、通道配置5.1 Telegram创建 Bot在 Telegram 中搜索 BotFather发送/newbot命令按提示设置 Bot 名称保存生成的 Token配置 OpenClawopenclaw configsetchannels.telegram.botTokenyour-bot-tokenopenclaw configsetchannels.telegram.allowedUsers[123456789]测试# 在 Telegram 中向你的 Bot 发送消息# 或使用 CLIopenclaw message send--totelegram--message测试消息5.2 Discord创建应用访问 Discord Developer Portal创建应用并获取 Bot Token启用必要的 IntentsMessage Content邀请 Bot 到服务器配置openclaw configsetchannels.discord.botTokenyour-bot-tokenopenclaw configsetchannels.discord.allowedGuilds[guild-id]5.3 Slack创建应用访问 Slack API创建应用并启用 Bot 用户配置 OAuth 权限安装到工作区配置openclaw configsetchannels.slack.botTokenxoxb-your-tokenopenclaw configsetchannels.slack.appTokenxapp-your-token5.4 其他通道OpenClaw 还支持WhatsApp通过 WebSignaliMessage仅 macOSMatrixMicrosoft TeamsZalo详细配置见https://docs.openclaw.ai/channels六、进阶使用6.1 技能Skills查看已安装技能openclaw skills list安装社区技能# 从 Clawhub 安装openclaw skillsinstallclawhub/weather# 从 GitHub 安装openclaw skillsinstallhttps://github.com/user/skill创建自定义技能创建~/.openclaw/skills/my-skill/skill.md# 我的技能 ## 描述 这是一个自定义技能示例。 ## 使用场景 - 任务 1 - 任务 2 ## 工具 - tool1: 功能描述 - tool2: 功能描述6.2 插件开发创建插件mkdirmy-plugincdmy-pluginnpminit-ynpminstallopenclawindex.jsexportdefault{name:my-plugin,version:1.0.0,asynconLoad(){console.log(Plugin loaded!);},tools:[{name:my-tool,description:我的自定义工具,inputSchema:{type:object,properties:{message:{type:string}}},handler:async(input){return{result:Hello${input.message}};}}]};安装插件openclaw pluginsinstall./my-plugin6.3 记忆系统配置记忆插件# 内置文件记忆openclaw configsetmemory.typefileopenclaw configsetmemory.path~/.openclaw/memory# 向量数据库需要额外配置openclaw configsetmemory.typevector使用记忆# 在对话中AI 会自动使用记忆openclaw agent--message记住我喜欢咖啡openclaw agent--message我喜欢的饮料是什么# AI 会检索记忆6.4 自动化与 Cron创建定时任务# 每天早上 9 点发送摘要openclawcroncreate--schedule0 9 * * *\--message生成今日任务摘要\--outputtelegram管理定时任务openclawcronlist openclawcrondeletetask-id6.5 Canvas 交互OpenClaw 支持 Canvas 渲染openclaw agent--message画一个饼图显示数据分布Canvas 配置{canvas:{enabled:true,maxWidth:1024,maxHeight:768}}七、故障排查7.1 诊断工具# 运行诊断openclaw doctor# 检查配置openclaw config validate# 查看日志openclaw logs--tail1007.2 常见问题问题 1Gateway 无法启动# 检查端口占用lsof-i:18789# 更换端口openclaw gateway run--port18790问题 2通道连接失败# 检查 Token 配置openclaw channels status--probe# 重新配置通道openclaw configsetchannels.telegram.botTokennew-token问题 3模型调用失败# 检查 API 密钥openclaw modelstest# 切换模型openclaw configsetmodels.defaultanthropic问题 4权限被拒绝# 检查文件权限ls-la~/.openclaw/# 修复权限chmod600~/.openclaw/openclaw.jsonchmod600~/.openclaw/.env7.3 日志调试启用详细日志exportDEBUG* openclaw gateway run--verbose查看特定模块日志exportDEBUGopenclaw:gateway,openclaw:channels openclaw gateway runmacOS 日志查看./scripts/clawlog.sh--follow八、最佳实践8.1 安全建议1. 保护 Gateway Token# 使用强随机 Tokenopenssl rand-hex32# 不要将 Token 提交到 Gitecho.env.gitignoreecho*.token.gitignore2. 限制通道访问{channels:{telegram:{allowedUsers:[trusted-user-id],adminUsers:[admin-user-id]}}}3. 使用命令白名单{security:{execApproval:{autoApprove:[ls,pwd,echo],requireApproval:[rm,sudo,curl],deny:[rm -rf /,format]}}}4. 网络隔离# 仅监听本地openclaw gateway run--bind127.0.0.1# 使用 SSH 隧道访问ssh-L18789:localhost:18789 userremote8.2 性能优化1. 连接复用{models:{cacheEnabled:true,cacheTTL:3600000}}2. 并发限制{gateway:{maxConcurrentRequests:10,rateLimit:{windowMs:60000,max:100}}}3. 响应流式传输openclaw agent--message长文本任务--stream8.3 配置管理1. 使用环境变量# .envOPENAI_API_KEYsk-...TELEGRAM_BOT_TOKEN...# openclaw.json{models:{providers:{openai:{apiKey:${OPENAI_API_KEY}}}}}2. 配置文件分离~/.openclaw/ ├── openclaw.json # 主配置 ├── .env # 敏感信息 ├── skills/ # 自定义技能 └── sessions/ # 会话日志3. 版本管理# 锁定版本openclaw update--channelstable# 查看更新openclaw update--check# 更新到最新openclaw update8.4 开发建议1. 测试配置# 测试模型连接openclaw modelstest# 测试通道连接openclaw channels status--probe# 测试工具调用openclaw agent--message测试工具2. 调试模式# 启用调试exportDEBUGopenclaw:*# 保存日志openclaw gateway run--verbose21|teegateway.log3. 监控与健康检查# 健康检查openclaw health# 状态监控watch-n5openclaw status九、进阶场景9.1 多模型故障转移{models:{providers:{openai:{apiKey:${OPENAI_API_KEY},priority:1,cooldownMs:60000},anthropic:{apiKey:${ANTHROPIC_API_KEY},priority:2,cooldownMs:60000}},failover:{enabled:true,maxRetries:3}}}9.2 Docker 部署FROM node:22-slim # 安装 OpenClaw RUN npm install -g openclawlatest # 复制配置 COPY .env /root/.openclaw/.env COPY openclaw.json /root/.openclaw/openclaw.json # 暴露端口 EXPOSE 18789 # 启动 CMD [openclaw, gateway, run, --bind, 0.0.0.0]# 构建并运行dockerbuild-topenclaw.dockerrun-d-p18789:18789 --env-file .env openclaw9.3 云平台部署Fly.ioflyctl launch flyctl deployDigitalOceandoctl apps create openclaw doctl apps deploy十、资源与社区10.1 官方资源GitHub: https://github.com/openclaw/openclaw文档: https://docs.openclaw.aiDiscord: https://discord.gg/clawdClawHub: https://clawhub.ai10.2 社区插件搜索和安装社区插件openclaw plugins search openclaw pluginsinstallclawhub/plugin-name10.3 贡献指南欢迎贡献代码、技能和插件Fork 仓库创建功能分支提交 Pull Request等待审核详见CONTRIBUTING.md十一、总结OpenClaw 是一个强大且灵活的 AI 智能体框架快速开始# 1. 安装npminstall-gopenclawlatest# 2. 配置向导openclaw onboard# 3. 启动服务openclaw gateway run--daemon# 4. 开始使用openclaw agent--message你好核心优势本地优先数据安全多通道统一管理高度可定制活跃的社区支持下一步探索更多通道配置开发自定义技能参与社区贡献祝你在 AI 自动化之旅中收获满满