OpenClaw 完全指南：开源个人 AI 助手的安装、配置与渠道接入

OpenClaw 是开源的「个人 AI 助手」：本地跑 Gateway，用 Telegram、WhatsApp、Discord 等跟你对话，支持技能与持久记忆。下面从安装写到使用和渠道配置，由浅入深。

简介与特点

• 开源：openclaw/openclaw，可自托管
• 多渠道：Telegram、WhatsApp、Discord、Slack、Google Chat、Mattermost、Signal、iMessage
• Gateway：本地起一个服务（默认 18789），桌面/手机/CLI 都连它
• 工作区：技能、提示词、记忆在 ~/.openclaw/workspace，可单独备份
• 多模型：Anthropic、OpenAI（含 Codex）、xAI、MiniMax、Moonshot、自定义 API 等
• 安全：私聊默认要配对审批；Gateway 可只绑 127.0.0.1、开 Token 认证

安装

环境：Node.js 22+，macOS / Linux（含 WSL）/ Windows（PowerShell）。安装脚本会帮你装 Node 和 Git。

一键安装脚本

macOS / Linux：

curl -fsSL --proto "=https" --tlsv1.2 https://openclaw.ai/install.sh | bash

Windows（PowerShell）：

iwr -useb https://openclaw.ai/install.ps1 | iex

Linux 报错 libatomic.so.1：先装系统库再试：

sudo dnf install -y libatomic
# 没有的话再试
sudo dnf install -y libgcc

手动安装

macOS / Linux 系统上，先安装 Homebrew，再使用 Homebrew 安装 NodeJs：

# 下载并安装 Homebrew
curl -o- https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash
# 设置国内源
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors4.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors4.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_INSTALL_FROM_API=1

# 下载并安装 Node.js：
brew install node@24

# 验证 Node.js 版本：
node -v # Should print "v24.15.0".

# 验证 npm 版本：
npm -v # Should print "11.12.1".

window 系统使用 powershell 下载 Chocolatey，再用 Chocolatey 安装 NodeJs：

# 下载并安装 Chocolatey：
powershell -c "irm https://community.chocolatey.org/install.ps1|iex"
# 下载并安装 Node.js：
choco install nodejs --version="24.15.0"
# 验证 Node.js 版本：
node -v # Should print "v24.15.0".
# 验证 npm 版本：
npm -v # Should print "11.12.1".

设置 npm 镜像 (加速国内下载)：

npm config set registry https://registry.npmmirror.com

再使用 npm 安装 openclaw：

# npm 全局安装
npm install -g openclaw@latest

使用 Docker 安装

mkdir -p /opt/openclaw/{config,logs,data}
sudo chmod 755 /opt/openclaw/*

docker run -d \
 --name openclaw \
 --restart always \
 -p 18789:18789 \
 -v /opt/openclaw/config:/app/config \
 -v /opt/openclaw/logs:/app/logs \
 -v /opt/openclaw/data:/app/data \
 -e TZ=Asia/Shanghai \
 openclaw/openclaw:2026-latest

docker ps | grep openclaw

# 1. 进入OpenClaw容器内部
docker exec -it openclaw bash
# 2. 生成管理员访问Token（务必保存，用于后续登录）
openclaw token generate --admin
# 3. 重启服务使配置生效
openclaw restart
# 4. 退出容器
exit

# 浏览器输入http://服务器公网IP:18789/?token=你的管理员Token，成功进入OpenClaw管理界面即部署完成，可进行后续MCP配置。

安装结束后会跑一遍引导向导，可以跳过后面再做配置。根据提示信息完成 OpenClaw 配置，参考配置如下：

基本配置

除了在安装时可以进行配置之外，还可以通过 Dashboard 网页进行配置，或者直接修改配置文件进行配置。可以参考阿里云的文档在 OpenClaw 中配置 Coding Plan。

使用

常用 CLI 命令速览：

更多用 openclaw <命令> --help 看。

启动 Web UI

新开一个终端，运行以下命令。

openclaw dashboard

本机浏览器打开 http://127.0.0.1:18789/ 在聊天页面可以进行对话。

如果安装 OpenClaw 的服务器 没有图形界面：openclaw dashboard 不会自动弹浏览器， 终端会打出一段说明（程序输出 ，不是要你执行的命令）。

OpenClaw 2026.3.2 (85377a2) — Give me a workspace and I'll give you fewer tabs, fewer toggles, and more oxygen.

Dashboard URL: http://127.0.0.1:18789/
Copy to clipboard unavailable.
No GUI detected. Open from your computer:
ssh -N -L 18789:127.0.0.1:18789 root@xxx.xxx.xxx.xxx
Then open:
http://localhost:18789/
Docs:
https://docs.openclaw.ai/gateway/remote
https://docs.openclaw.ai/web/control-ui

提示你需要在本机做 SSH 端口转发再访问。

ssh -L 18789:127.0.0.1:18789 root@你的服务器

然后在本地浏览器打开 http://127.0.0.1:18789/。

启动 TUI

新开一个终端，运行以下命令，进入TUI 界面。

openclaw tui

然后可以开始对话。

启动网关

Gateway 是本地常驻服务，Dashboard、TUI、各渠道（Telegram/飞书等）都连它。 不先起网关，网页和机器人都不通。

前台跑（调试用）

openclaw gateway

openclaw gateway --verbose # 输出日志

占住当前终端，默认端口 18789。改端口用 openclaw gateway --port 端口号。 Ctrl+C 停掉。

后台跑（日常用）

openclaw gateway start
openclaw gateway restart
openclaw gateway stop
openclaw gateway status

改完配置（渠道、模型等）后记得 openclaw gateway restart 让配置生效。

端口与安全

端口在配置里 gateway.port，默认 18789。 若只在本机用，可把 gateway.host 设为 127.0.0.1； 要远程访问再绑 0.0.0.0，并建议开 gateway.authToken，详见 Gateway 文档。

高级配置

模型提供商配置

使用 codex team 登录：

openclaw models auth login --provider openai-codex

渠道管理

添加飞书渠道

官方文档描述的非常详细，可以直接参照文档进行操作。

以下是通过 CLI 添加频道：

openclaw channels add

选择飞书，然后输入应用 ID 和应用密钥。

然后，启动网关。

openclaw gateway

在飞书中找到你的机器人并发送消息。

默认情况下，机器人会回复一个配对码。请批准该配对码：

openclaw pairing approve feishu <CODE>

审核通过后，即可正常聊天。

添加 Telegram 渠道

1. 拿 Bot Token

Telegram 里找 @BotFather，发 /newbot，按提示建机器人，把给的 token 存好（长得像 123456789:ABCdef...）。

2. 通过 CLI 添加频道

openclaw channels add

选择Telegram，然后输入 token。

设置 requireMention（仅 @ 才回复）
群聊里若希望只有 @ 了机器人才回复，在 channels.telegram 里加一个 groups 段，设 requireMention: true。
编辑 ~/.openclaw/openclaw.json 或 Dashboard 配置 → RAW，在已有 telegram 配置中增加 groups 即可，例如：

"telegram": {
"enabled": true,
"configWrites": true,
"dmPolicy": "pairing",
"botToken": "你的 token",
"groupAllowFrom": [],
"groupPolicy": "open",
"groups": {
"*": {"requireMention": true}
},
"chunkMode": "length",
"streaming": "partial"
}

"*" 表示所有群都生效；也可对单个群用群组 ID（如 "-1001234567890"）单独设。改完执行 openclaw gateway restart。

3. 第一次私聊要配对

启动网关并批准第一个私信

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

配对码1小时后失效。

4. 群聊

把 bot 拉进群。如果配了 requireMention: true，得在群里 @ 它才会回。 想看到所有群消息：在群里设成管理员，或 @BotFather 里对 bot 用 /setprivacy 关隐私。

5. 主动发消息

已经配对或进了 allowlist 的，可以这样发：

openclaw message send --target telegram:1990681746 --message "你好"

--target 的写法：

• 私聊： telegram:123456789（对方数字 user id）。
• 群组：telegram:-100xxxxxxxxxx（群组 chat_id，一般为负的 long 数字）。 chat_id 可在群组里先发一条消息，用 openclaw pairing list telegram 等看到；或通过 Telegram Bot API 获取。

小龙虾初始化

刚开始的时候，和小龙虾聊天，需要告诉它你是谁，以下是一个模版。

我叫 XX，今年 XX 岁，在 XX 城市做 XX 工作，主要负责 XX 内容。我平时不喜欢太正式的说话方式，你跟我沟通可以随意一点。我每天 XX 点上班，平时 XX 点睡觉。我目前在 XX / 有 XX 习惯，相关内容麻烦多提醒我

技能

技能用来扩展 agent 能力：搜网、查天气、读文件、调 API 等，由 agent 在对话或定时任务里按需调用。

技能从三个位置加载，优先级从高到低：工作区 ~/.openclaw/workspace/skills、本地管理 ~/.openclaw/skills、内置 （随安装）。同名时工作区覆盖本地，本地覆盖内置。

查看与检查

openclaw skills list              # 已加载的技能
openclaw skills list --eligible   # 满足依赖、可用的
openclaw skills info <技能名>     # 详情
openclaw skills check             # 检查 bundled/workspace 技能是否缺依赖

安装技能

• ClawHub（推荐）：从社区技能库安装到工作区。需先装 ClawHub CLI。

  # 安装 clawhub
  npm i -g clawhub
  
  # 搜索
  clawhub search "weather"
  
  # 安装天气查询技能
  clawhub install weather
  
  # 列出所有已安装技能及启用状态
  openclaw skills list
  
  # 更新单个技能到最新版本
  clawhub update weather
  # 一键更新所有已安装技能
  clawhub update --all
  
  # 发布
  clawhub publish ./my-skill --slug my-awesome-skill
  clawhub sync ./skills-folder --dry-run  # 批量发布预览
  
  # 卸载不需要的技能
  clawhub uninstall weather

• 手动：把技能目录放到 ~/.openclaw/workspace/skills/ 下，结构符合 Creating Skills 即可。

配置

在 ~/.openclaw/openclaw.json 的 skills 段里可做：启用/禁用某个技能、配 API Key、设 env、限制内置技能（allowBundled ）、调整加载目录（load.extraDirs）等。 改完一般无需重启 Gateway，下次 agent 执行时会生效；若未生效可 openclaw gateway restart。

定时任务

OpenClaw 自带 Cron：按时间或间隔跑一次「完整 agent 轮次」（可搜网、用工具、写记忆），并把结果发到指定渠道，适合每日简报、周报、提醒等。

添加任务

openclaw cron add --name morning-brief --cron "30 6 * * *" --message "每日简报"

管理任务

openclaw cron list          # 列出所有任务
openclaw cron remove <id>  # 删除
openclaw cron pause <id>   # 暂停

任务持久化在 ~/.openclaw/cron/jobs.json，重启 Gateway 不会丢。更多选项（如 webhook、隔离/主会话模式）见 Cron 文档。

使用场景

参考 OpenClaw AI 智能体最佳真实用例大全。

推荐一些skills:

• tavily-search，每个月1000次免费调用，不用绑卡。好处就是它本身就是专门给Agent做的搜索API，返回的内容处理过了。
• find-skills，遇到解决不了的任务时，Agent 能自己去ClawHub检索并安装合适的Skills。
• self-improving，是让Agent记住执行中的错误并自我修正，用的越多逻辑就越顺。
• proactive-agent，主动规划模块，这样OpenClaw就有了自主拆解和多步任务的权限。
• gog (Google 全家桶)，支持读取邮箱（我订阅的日报就是靠这个总结）和日历排期。
• summarize，用来做高密度信息摘要的，把长篇的URL，PDF或音视频丢个OpenClaw，它能快速提取核心论点

以下是对我有用的以下使用场景

1、使用 clinkding 技能保存书签到 Linkding

clinkding config -u https://linkding.zhijun.io -t YOUR_TOKEN

# 重启 gateway
openclaw gateway restart 

clinkding 技能安装之后，给机器人发消息，比如：“保存书签 https://github.com/AlexAnys/awesome-openclaw-usecases-zh”，机器人就会调用配置的 clinkding 服务的 API 接口保存书签。

附录

配置文件说明

主要路径：

环境变量（可选）： OPENCLAW_CONFIG_PATH 换配置文件；OPENCLAW_STATE_DIR 换状态目录；OPENCLAW_HOME 换内部用的「家目录」。

用 Dashboard 改配置： openclaw dashboard 打开网页，左侧 配置 → All Settings → RAW， 编辑的就是 openclaw.json。改完点 Save 再 Update。

注意：已有渠道、模型时别整段覆盖 Raw JSON，只改要改的那几块 （如 models、agents、gateway）。缺键再补。

接阿里云百炼 Coding Plan：在 Raw JSON 里加 models.providers 和 agents.defaults.model，把 YOUR_API_KEY 换成真实 Key。

示例和模型列表见 阿里云文档。

更新与维护

• npm 装的：npm update -g openclaw（或你实际包名）
• git 装的：进克隆目录 git pull、pnpm install，再装一遍 CLI 包装
• 自己改的东西尽量只放在 ~/.openclaw/workspace 和 ~/.openclaw/openclaw.json，升级时不会盖掉

常见问题

报错：No API key found for provider “anthropic”（或别的 provider） 说明当前用的 agent（例如 main）没配这个模型的认证。 要么给这个 agent 配一遍：openclaw agents add main，按提示选 provider、填 Key； 要么从已经配好的 agent 拷认证文件过去，例如：

cp /root/.openclaw/agents/default/agent/auth-profiles.json \
   /root/.openclaw/agents/main/agent/auth-profiles.json

认证是按 agent 存的，路径在 ~/.openclaw/agents/<agent>/agent/auth-profiles.json。 Onboarding 一般只给默认 agent 写了认证，换了 agent 或迁过目录就要单独配或拷一份。

报错：clawhub install xxx — Rate limit exceeded
ClawHub registry 对请求做了限流（同一 IP 或短时间请求过多）。处理方式：先试 npx clawhub install <技能名>，往往能正常安装；若仍失败，等 10–30 分钟再试、关 VPN 或换网络、避免连续重试（会拉长限流时间）。

参考链接

• OpenClaw 官网
• Getting Started
• 安装脚本说明（install.sh / install-cli.sh）
• Onboarding 向导
• CLI Onboarding 参考
• Setup（工作区与配置）
• 渠道配置（Telegram、Discord、WhatsApp 等）