OpenClaw 入门完整教程：从零搭建自托管AI网关

OpenClaw入门到实战自托管AI网关完整部署指南作者鲲鹏AI探索局 | 标签OpenClaw, AI Agent, 自托管, 多平台聊天, 网关部署摘要本文详细介绍OpenClaw——一个开源自托管AI网关的安装、配置和实战部署全过程。通过实际案例演示如何连接Telegram、Discord、飞书等20聊天平台实现数据完全可控的AI助手。特别针对中国用户的Windows环境、网络问题、飞书接入提供详细解决方案。关键词OpenClaw, AI网关, 自托管, 多平台集成, 隐私保护, 飞书机器人, Windows部署, Ollama一、OpenClaw技术架构深度解析1.1 OpenClaw核心设计OpenClaw是一个插件化AI网关采用Node.js TypeScript开发核心架构分为三层┌─────────────────────────────────────┐ │ Chat Platforms Layer │ │ (Telegram, Discord, Feishu, ...) │ └───────────────┬─────────────────────┘ │ HTTP/Webhook ┌───────────────▼─────────────────────┐ │ OpenClaw Gateway │ │ ┌────────────┐ ┌──────────────┐ │ │ │ Router │ │ Plugins │ │ │ └────────────┘ └──────────────┘ │ └───────────────┬─────────────────────┘ │ Provider API ┌───────────────▼─────────────────────┐ │ AI Providers Layer │ │ (OpenAI, Anthropic, Ollama, ...) │ └─────────────────────────────────────┘核心组件:Gateway: 主服务进程监听HTTP端口默认8080Router: 消息路由根据配置分发到不同AI模型Plugins: 平台适配器Telegram、Discord、Feishu等Models: AI模型抽象层统一接口1.2 技术栈运行时: Node.js 24.x (22.14 supported)语言: TypeScript通信协议: HTTP Webhook Bot APIs配置格式: JSON5支持注释插件系统: 动态加载热重载1.3 应用场景场景说明推荐配置个人AI助手通过Telegram/Discord/飞书与AI对话云端API 本地缓存企业内网数据不出内网合规要求Ollama本地模型24小时客服自动回复常见问题固定prompt 知识库IoT智能体树莓派部署控制智能家居轻量模型 自定义技能二、环境搭建与安装实战2.1 系统要求组件最低配置推荐配置说明OSWin10/WSL2Ubuntu 22.04WSL2性能最佳Node.js22.1424.x官方推荐RAM2GB4GBOllama需更多Disk1GB5GB含模型文件Network可访问AI API低延迟本地模型不需要2.2 安装方案对比Windows用户重点方案对比表方案安装难度运行性能稳定性推荐指数适用人群WSL2⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐所有Win10/11用户Windows原生⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐不想用WSL的进阶用户Docker⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐已有Docker环境macOS/Linux⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐非Windows用户结论: Win10/11用户无脑选WSL22.3 WSL2安装详细步骤Step 1: 启用WSL2以管理员打开PowerShell# 启用WSL功能dism.exe/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart# 启用虚拟机功能dism.exe/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart# 重启计算机Restart-ComputerStep 2: 安装WSL2内核更新包访问 https://aka.ms/wsl2update 下载并安装。Step 3: 设置WSL2为默认版本wsl--set-default-version 2Step 4: 安装Ubuntu打开Microsoft Store搜索Ubuntu点击安装推荐Ubuntu 22.04 LTS。首次启动Ubuntu设置用户名和密码与Windows账户无关。Step 5: 更新Ubuntu系统在Ubuntu终端中sudoaptupdatesudoaptupgrade-ysudoaptinstall-ycurlgitStep 6: 配置Node.js使用nvm# 安装nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh|bash# 加载nvmsource~/.bashrc# 安装Node.js 24nvminstall24nvm use24nvmaliasdefault24# 验证node--version# 应显示 v24.xnpm--versionStep 7: 安装OpenClawcurl-fsSLhttps://openclaw.ai/install.sh|bash安装脚本会自动检测系统环境安装OpenClaw CLI如果npm未安装会先安装运行openclaw onboard交互式配置可选安装为系统服务Step 8: 验证安装openclaw--version# 输出: OpenClaw 2026.3.24openclaw status# 应显示 Gateway: running三、配置AI模型关键决策3.1 AI Provider选择指南Provider是否需要代理成本响应速度质量推荐场景OpenAI✅ 需要按token快⭐⭐⭐⭐⭐高质量对话、代码Anthropic✅ 需要按token中⭐⭐⭐⭐⭐长文本、安全性Ollama❌ 不需要0硬件取决于配置⭐⭐⭐⭐国内用户、隐私优先Google Gemini✅ 需要按token快⭐⭐⭐⭐多模态图像Azure OpenAI✅ 需要按token快⭐⭐⭐⭐⭐企业Azure环境中国用户推荐组合:主模型: Ollamallama3.2:3b轻量速度快备用模型: OpenAIgpt-4o-mini质量高按需使用3.2 Ollama本地部署0成本方案安装Ollama在WSL2 Ubuntu中curl-fsSLhttps://ollama.com/install.sh|sh验证安装ollama--version# Ollama is running# 查看服务状态systemctl status ollama# 应显示 active (running)下载模型# 轻量模型推荐新手ollama pull llama3.2:3b# 中等模型质量更好ollama pull mistral# 代码专用ollama pull codellama:7b测试Ollamaollama run llama3.2:3b你好请介绍一下你自己应该收到模型回复。OpenClaw配置Ollama编辑配置openclaw config edit修改models.default:{ models: { default: { provider: ollama, model: llama3.2:3b, baseUrl: http://localhost:11434 } } }重启网关openclaw restart3.3 OpenAI配置需API key获取API key访问 https://platform.openai.com/api-keys登录可能需要代理点击Create new secret key复制key格式sk-...⚠️国内提醒: OpenAI API需要国际信用卡可通过正规渠道代购注意风险OpenClaw配置{ models: { default: { provider: openai, model: gpt-4o-mini, // 性价比高 apiKey: sk-你的密钥 } } }四、平台连接实战4.1 Telegram最简单1. 创建Bot打开Telegram搜索 BotFather发送/newbot输入Bot名称如MyOpenClawBot输入用户名需唯一如my_openclaw_bot复制BotFather返回的Bot Token2. 配置OpenClawopenclaw config edit在plugins添加{ plugins: { telegram: { botToken: 你的Bot Token } } }3. 重启并测试openclaw restart在Telegram中打开你的Bot发送你好收到AI回复即成功4.2 Discord企业协作1. Discord开发者门户配置访问 https://discord.com/developers/applicationsNew Application→ 输入名称 → Create左侧Bot→ Add Bot → Yes, do it!复制Token类似MTk...Privileged Gateway Intents开启✅ Presence Intent✅ Server Members Intent✅ Message Content Intent2. 邀请Bot到服务器左侧OAuth2→ URL GeneratorScopes: 勾选botBot Permissions: 选择Send Messages,Read Message History等最小权限原则复制生成的URL在浏览器打开选择服务器并授权3. OpenClaw配置{ plugins: { discord: { token: 你的Bot Token, clientId: 你的Application ID, allowedChannels: [] // 可选限制频道ID } } }重启后在Discord中Bot测试。4.3 飞书国内重点详细步骤前置条件企业飞书账号或个人开发者账号已备案域名Webhook要求HTTPS服务器公网IP或内网穿透Step 1: 创建飞书应用访问 https://open.feishu.cn/app点击创建应用 → 选择自建应用填写应用名称:OpenClaw助手应用描述:基于OpenClaw的AI助手上传图标可选点击创建Step 2: 配置权限权限管理→ 添加权限im:message # 发送和接收消息 im:chat # 获取群组信息可选订阅事件→ 添加事件订阅im.message.receive_v1 # 接收消息事件Step 3: 获取凭证应用首页 → 复制App ID格式cli_...App Secret格式...Step 4: 安装OpenClaw飞书插件openclaw pluginsinstallfeishuStep 5: 配置OpenClaw编辑~/.openclaw/config.json:{ plugins: { feishu: { appId: cli_xxxxxxxxxxxxx, appSecret: xxxxxxxxxxxxxxxxxxxx, encryptionKey: 可选32位随机字符串提高安全性 } } }保存并重启openclaw restartStep 6: 获取Webhook URLopenclaw urls输出示例Feishu event URL: https://your-domain.com/api/plugins/feishu/events重要: 确保该URL满足✅ HTTPS飞书强制要求✅ 公网可访问飞书服务器能访问✅ 域名已备案国内要求Step 7: 配置事件订阅飞书开发者后台事件订阅→ 添加订阅事件类型:im.message.receive_v1Request URL: 粘贴上一步的URL点击保存并启用如果验证失败检查HTTPS证书是否有效Let’s Encrypt免费证书检查Nginx配置是否正确查看OpenClaw日志:openclaw logs | grep feishuStep 8: 安装机器人左侧机器人→ 添加机器人选择自定义复制机器人App ID和App Secret与步骤3相同点击安装到 → 选择全员或指定部门/群组Step 9: 测试在飞书中打开任意聊天窗口或群组你的机器人发送消息应收到AI回复调试技巧:# 查看飞书相关日志openclaw logs--follow|grepfeishu# 验证Webhook是否收到事件# 在飞书开发者后台 → 事件订阅 → 查看最近事件五、故障排查全攻略5.1 日志查看与解读查看实时日志# 实时日志默认info级别openclaw logs--follow# 调试级别更详细openclaw logs--follow--leveldebug# 仅查看错误openclaw logs--levelerror# 查看最近N行openclaw logs--tail100日志分析示例# 正常请求 [INFO] 2026-03-30T14:20:00.123Z gateway: received message from telegram user 12345 [INFO] 2026-03-30T14:20:00.456Z model: calling openai/gpt-4o (tokens: 150) [INFO] 2026-03-30T14:20:01.789Z gateway: sent reply to telegram # 错误示例 [ERROR] 2026-03-30T14:20:00.456Z plugin.feishu: invalid appId or appSecret [WARN] 2026-03-30T14:20:00.789Z model: rate limit exceeded (429)5.2 健康检查openclaw doctor输出示例✔ Node.js: 24.0.0 ✔ Gateway: running (port 8080) ✔ Plugins: telegram, discord, feishu ✔ Models: ollama/llama3.2:3b ✗ Ollama: not running (if using local models, start with: ollama serve)5.3 常见错误代码错误码含义可能原因解决方案401未授权API key错误检查provider的apiKey403禁止访问权限不足检查Bot权限Discord、App权限飞书404未找到Webhook URL错误openclaw urls检查URL429限流API调用超限降低频率或升级plan500服务器错误OpenClaw内部错误查看日志openclaw logsECONNREFUSED连接拒绝AI服务未启动检查Ollama:ollama serveEADDRINUSE端口占用8080被其他程序占用修改gateway.port或停止占用进程5.4 端口占用排查# Windows管理员PowerShellnetstat-ano|findstr :8080# 记录PID然后:tasklist|findstrPID# WSL2 Ubuntusudonetstat-tulpn|grep:8080sudokill-9PID5.5 网络诊断# 测试到AI provider的网络pingapi.openai.comcurl-Ihttps://api.openai.com/v1/models# 测试Ollama本地连接curlhttp://localhost:11434/api/tags# 测试端口监听ss-tlnp|grep8080# Linuxnetstat-an|findstr8080# Windows六、生产环境部署6.1 Nginx反向代理必读OpenClaw默认监听127.0.0.1:8080生产环境需Nginx提供公网访问。安装NginxUbuntu:sudoaptinstallnginxWindows(WSL2): 同上或使用Windows原生Nginx配置站点编辑/etc/nginx/sites-available/openclaw:server { listen 80; server_name your-domain.com; # 你的域名或IP location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 300s; } }启用并测试sudoln-s/etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/sudonginx-t# 测试配置sudosystemctl reload nginxHTTPS配置飞书要求飞书要求Webhook必须HTTPS。# 安装Certbotsudoaptinstallcertbot python3-certbot-nginx# 获取免费SSL证书sudocertbot--nginx-dyour-domain.com# 自动续期测试sudocertbot renew --dry-run6.2 系统服务管理systemctlLinux# 安装为系统服务如果onboarding时未安装openclaw configsetgateway.daemon.enabledtrue# 管理服务sudosystemctl start openclaw-gatewaysudosystemctlenableopenclaw-gateway# 开机自启sudosystemctl status openclaw-gatewaysudosystemctl restart openclaw-gateway# 查看日志sudojournalctl-uopenclaw-gateway-fWindows Service# 查看服务Get-ServiceOpenClawGateway# 启动Start-ServiceOpenClawGateway# 停止Stop-ServiceOpenClawGateway# 重启Restart-ServiceOpenClawGateway# 设置开机自启Set-ServiceOpenClawGateway-StartupType Automatic6.3 自动备份策略备份脚本创建~/backup-openclaw.sh:#!/bin/bashBACKUP_DIR/backup/openclawOPENCLAW_DIR$HOME/.openclawDATE$(date%Y%m%d_%H%M%S)# 创建备份目录mkdir-p$BACKUP_DIR# 打包备份tar-czf$BACKUP_DIR/openclaw-$DATE.tar.gz-C$OPENCLAW_DIR.# 清理7天前的备份find$BACKUP_DIR-nameopenclaw-*.tar.gz-mtime7-deleteecho[INFO] Backup completed: openclaw-$DATE.tar.gz赋予执行权限chmodx ~/backup-openclaw.shCrontab定时备份crontab-e添加每天凌晨2点执行:0 2 * * * /home/yourname/backup-openclaw.sh /var/log/openclaw-backup.log 21七、性能优化建议7.1 模型选择策略场景推荐模型Token成本速度质量日常聊天gpt-4o-mini / llama3.2:3b低快良代码生成gpt-4o / codellama中中优复杂分析claude-3-5-sonnet高慢极优离线使用llama3.2:3b (Ollama)0取决于硬件良7.2 缓存配置减少重复API调用{ cache: { enabled: true, ttl: 3600, // 缓存1小时 maxSize: 1000 // 最多1000条 } }7.3 流式输出提升用户体验{ models: { default: { stream: true // 启用流式 } } }八、监控与告警8.1 日志轮转配置logrotateLinux:sudonano/etc/logrotate.d/openclaw内容/home/yourname/.openclaw/logs/*.log { daily rotate 30 compress delaycompress missingok notifempty create 644 yourname yourname postrotate systemctl restart openclaw-gateway /dev/null 21 || true endscript }8.2 异常告警结合cron jobs定期检查# 每小时检查网关状态openclawcroncreate--schedule0 * * * *\--message检查OpenClaw状态\--to1234567890九、进阶功能9.1 多平台差异化身份不同平台显示不同名称和性格{ channels: { telegram: { agent: { name: TG助手, systemPrompt: 简洁适合手机阅读最多3句话。 } }, discord: { agent: { name: Discord Bot, systemPrompt: 活泼可以适当使用emoji。 } }, feishu: { agent: { name: 飞书助手, systemPrompt: 专业适合工作场景。 } } } }9.2 自定义技能开发技能是OpenClaw的扩展功能用TypeScript编写。示例计算器技能~/.openclaw/skills/calculator.ts:import{Skill}fromopenclaw;exportdefault{name:calculator,triggers:[计算,calculate,calc],asyncexecute(context){constexprcontext.args.join( );try{// ⚠️ 生产环境不要用evalconstresulteval(expr);return计算结果:${result};}catch(e){return计算失败:${e.message};}}}asSkill;重启OpenClaw后即可使用机器人 “计算 12*34”十、总结与展望OpenClaw提供了一个灵活、可控、可扩展的AI助手解决方案。核心优势总结数据主权- 所有数据在本地无隐私泄露风险平台中立- 20平台一次配置处处可用模型自由- 任意provider随时切换成本可控- 无月费只付API费用或本地0成本开放生态- 插件化架构社区可贡献适用场景评估场景是否适合理由个人开发者✅ 强烈推荐隐私保护多平台统一技术爱好者✅ 推荐可定制性强折腾乐趣企业内网✅ 推荐数据不出内网合规完全不想折腾的用户❌ 不推荐直接用ChatGPT更省心超大并发需求⚠️ 需评估单网关约100并发大规模需集群未来路线图根据GitHub IssuesOpenClaw计划 更多平台微信原生、钉钉 多网关集群管理 可视化配置Web UI 技能市场社区插件商店 RAG集成知识库检索参考资料OpenClaw官方文档GitHub仓库Discord社区支持的平台列表自动化指南技能开发作者: 鲲鹏AI探索局转载请注明出处: https://kunpeng-ai.com/blog/openclaw-getting-started最后更新: 2026-03-31OpenClaw版本: 2026.3.24