OpenClaw 安装与配置教程OpenClaw 是一款可私有部署的个人 AI 助手运行在你自己的设备上支持通过多种即时通讯工具WhatsApp、Telegram、Slack、Discord、飞书等进行交互。一、环境要求运行时环境Node.js ≥ 22.16推荐 Node 24npm ≥ 10包管理器推荐使用 pnpm构建和安装更稳定支持平台macOSLinuxWindows二、基础安装方式一npm 安装通用npminstall-gopenclawlatest方式二pnpm 安装推荐pnpmadd-gopenclawlatest方式三Bun 安装buninstall-gopenclawlatest从源码安装开发用途gitclone https://github.com/openclaw/openclaw.gitcdopenclawpnpminstallpnpmui:build# 首次运行自动安装 UI 依赖pnpmbuild# 开发模式源码/配置变更自动重载pnpmgateway:watch三、初始化配置安装完成后使用 Onboard 向导完成初始化openclaw onboard --install-daemon该命令会引导你完成 Gateway 守护进程安装配置工作空间默认~/.openclaw/workspace设置 Channel 连接安装必要的 Skills--install-daemon参数会将 Gateway 注册为系统服务launchd/systemd确保开机自启。四、配置流程个人觉得最方便的配置方法还得是交互式配置只需要通过openclaw config或openclaw configure进行配置就好了4.1 选择运行模式OpenClaw 支持多种运行模式本地模式Gateway 运行在本地适合个人使用远程模式Gateway 运行在 Linux 服务器通过 Tailscale 或 SSH 隧道访问4.2 配置 AI 模型编辑~/.openclaw/openclaw.json{ agent: { model: provider/model-id } }支持的模型提供商OpenAIChatGPT/Codex需 OAuth 或 API Key其他主流大模型提供商模型配置文档模型选择与认证ModelsOAuth 与 API Key 轮换Model Failover4.3 认证配置根据选择的渠道配置相应认证信息Telegram{ channels: { telegram: { botToken: 123456:ABCDEF } } }Discord{ channels: { discord: { token: 你的 Bot Token } } }Slack需要配置SLACK_BOT_TOKEN和SLACK_APP_TOKEN环境变量或在配置文件中设置channels.slack.botToken和channels.slack.appToken。完整配置参考Configuration Reference五、常用命令5.1 管理命令# 启动 Gateway指定端口和详细日志openclaw gateway--port18789--verbose# 查看 Gateway 状态openclaw gateway status# 重启 Gatewayopenclaw gateway restart# 健康检查openclaw doctor# 更新 OpenClawopenclaw update--channelstable|beta|dev5.2 Agent 命令# 发送消息给 Agentopenclaw agent--message你的问题--thinkinghigh# 列出活跃会话openclaw sessions list# 查看会话历史openclaw sessionshistory--sessionsession-id5.3 Channel 命令# 登录 Channel如 WhatsApp、微信等openclaw channels login# 登录指定 Channelopenclaw channels login--channelchannel-name# 发送消息openclaw message send--to1234567890--messageHello from OpenClaw5.4 Skill 命令# 列出已安装 Skillsopenclaw skills list# 安装新 Skillopenclaw skillsinstallskill-name# 卸载 Skillopenclaw skills uninstallskill-name5.5 聊天命令在聊天窗口中使用在已连接的聊天渠道中发送/status— 查看会话状态模型、Token 消耗/new或/reset— 重置会话/compact— 压缩会话上下文生成摘要/think level— 设置思考等级off|minimal|low|medium|high|xhigh/verbose on|off— 切换详细输出/usage off|tokens|full— 设置用量显示模式/restart— 重启 Gateway群聊中仅群主可用/activation mention|always— 群聊激活模式切换六、守护进程配置6.1 macOSlaunchdonboard --install-daemon会自动创建 launchd 服务。手动管理# 查看服务状态launchctl list|grepopenclaw# 停止服务launchctl unload ~/Library/LaunchAgents/io.openclaw.gateway.plist# 启动服务launchctl load ~/Library/LaunchAgents/io.openclaw.gateway.plist6.2 Linuxsystemdonboard --install-daemon会自动创建 systemd 用户服务。手动管理# 查看服务状态systemctl--userstatus openclaw-gateway# 启动服务systemctl--userstart openclaw-gateway# 停止服务systemctl--userstop openclaw-gateway# 开机自启systemctl--userenableopenclaw-gateway# 查看日志journalctl--user-uopenclaw-gateway-f6.3 后台进程模式如果不使用守护进程可使用后台运行# 使用 nohupnohupopenclaw gateway--port18789--verboseopenclaw.log21# 使用 screen 或 tmuxscreen-Sopenclaw openclaw gateway--port18789--verbose# CtrlA, D 退出 screen后台进程文档Background Process七、配置文件位置核心配置主配置文件~/.openclaw/openclaw.json凭证存储~/.openclaw/credentials/工作空间~/.openclaw/workspace/可配置Skills 目录~/.openclaw/workspace/skills/日志文件~/.openclaw/logs/工作空间文件AGENTS.md— Agent 行为协议SOUL.md— 人格设定IDENTITY.md— 身份标识USER.md— 用户信息TOOLS.md— 工具配置笔记模板文件位置默认 AGENTSAGENTS.default各类模板Templates八、常见问题Q1: Gateway 无法启动检查项# 检查 Node.js 版本node--version# 应 ≥ 22.16# 检查端口占用lsof-i:18789# 查看详细日志openclaw gateway--verboseQ2: Channel 连接失败排查步骤检查认证信息是否正确Token、API Key运行openclaw doctor检查配置查看渠道特定文档Channels检查网络连通性特别是 webhook 地址并且是不能轻易去使用代理的会导致请求不到通用排查指南TroubleshootingQ3: 权限问题macOSmacOS 需要授予以下权限辅助功能Accessibility屏幕录制Screen Recording通知Notifications权限管理macOS PermissionsQ4: 模型调用失败解决方案检查模型配置是否正确验证 API Key 或 OAuth 状态配置模型故障转移Model Failover查看用量跟踪Usage TrackingQ5: 浏览器工具无法使用LinuxLinux 需要安装 Chromium 依赖# Debian/Ubuntusudoapt-getinstallchromium-browser# 或使用 OpenClaw 管理的浏览器openclaw browserinstall详细指南Browser TroubleshootingQ6: 如何更新 OpenClaw# 更新到最新版openclaw update# 切换到 Beta 频道openclaw update--channelbeta# 更新后检查openclaw doctor更新指南UpdatingQ7: DM 安全策略默认情况下陌生用户的私信会被拦截并返回配对码。批准配对openclaw pairing approvechannelcode开放私信不推荐在配置中设置dmPolicy: open并在allowFrom中包含*。安全指南Security快速开始TL;DR# 1. 安装pnpmadd-gopenclawlatest# 2. 初始化含守护进程openclaw onboard --install-daemon# 3. 启动 Gatewayopenclaw gateway--port18789--verbose# 4. 发送测试消息openclaw message send--to1234567890--messageHello from OpenClaw# 5. 与 Agent 对话openclaw agent--messageShip checklist--thinkinghigh参考文档官方文档索引架构概览配置参考安全指南Onboard 向导入门指南Discord 社区