OpenClaw 跨平台 AI 助手完全使用指南：从入门到进阶

配置文件示例：

{
  "models": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

二、安装与配置

2.1 系统要求

2.2 快速安装（推荐）

推荐使用 npm 或 pnpm 进行全局安装：

# 使用 npm 安装
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

# 或使用 bun
bun add -g openclaw@latest

初始化配置后，运行向导安装守护进程并启动网关：

# 运行向导安装守护进程
openclaw onboard --install-daemon

# 启动网关
openclaw gateway --port 18789 --verbose

验证安装是否成功：

# 检查版本
openclaw --version

# 运行健康检查
openclaw doctor

2.3 从源码安装（开发版）

如果你需要参与开发或测试最新功能，可以从源码构建：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建 UI
pnpm ui:build

# 构建项目
pnpm build

# 安装守护进程
pnpm openclaw onboard --install-daemon

# 开发模式运行（自动重载）
pnpm gateway:watch

2.4 Docker 安装

对于容器化部署，可以使用 Docker：

# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/openclaw/data:/data \
  openclaw/openclaw:latest

2.5 配置文件详解

OpenClaw 的配置文件通常位于 ~/.openclaw/openclaw.json，主要结构如下：

{
  "version": "2026.2.9",
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1",
    "verbose": false
  },
  "models": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "anthropicApiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "your-app-id",
      "appSecret": "your-app-secret"
    }
  },
  "skills": {
    "enabled": true,
    "installDir": "~/.openclaw/skills"
  }
}

环境变量配置：

# 设置 API 密钥
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

# 设置自定义配置路径
export OPENCLAW_CONFIG_PATH="~/.config/openclaw/openclaw.json"

# 设置数据目录
export OPENCLAW_STATE_DIR="~/.local/share/openclaw"

三、通道配置详解

OpenClaw 支持多种消息通道，以下是主流平台的配置方法。

3.1 飞书配置

1. 访问飞书开放平台创建企业自建应用。
2. 获取 App ID 和 App Secret。
3. 配置应用权限（消息、通讯录等）。

配置示例：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a5xxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "encryptKey": "your-encrypt-key",
      "verificationToken": "your-verification-token"
    }
  }
}

验证配置：

openclaw doctor --channel feishu

3.2 Telegram 配置

1. 联系 @BotFather 创建新机器人。
2. 获取 HTTP API Token。

配置示例：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-bot-token",
      "dmPolicy": "pairing"
    }
  }
}

3.3 Discord 配置

1. 访问 Discord Developer Portal 创建应用并添加 Bot。
2. 获取 Bot Token 并配置 Intent 权限。

配置示例：

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-bot-token",
      "dmPolicy": "pairing",
      "allowFrom": ["123456789", "987654321"]
    }
  }
}

3.4 消息策略配置

OpenClaw 提供多种消息处理策略以平衡便利性与安全性：

推荐配置：

{
  "channels": {
    "discord": {
      "dmPolicy": "pairing",
      "allowFrom": ["your-user-id"]
    }
  }
}

配对命令：

# 查看待配对请求
openclaw pairing list

# 批准配对
openclaw pairing approve discord 123456

# 拒绝配对
openclaw pairing reject discord 123456

四、核心功能详解

4.1 会话管理

OpenClaw 支持多种会话模式，满足不同使用场景。

主会话操作：

# 发送消息
openclaw message send --to +1234567890 --message "Hello!"

# 启动对话
openclaw agent --message "Help me write a summary"

# 带思考模式
openclaw agent --message "Analyze this code" --thinking high

会话状态查看：

# 查看当前会话
openclaw sessions list

# 查看会话历史
openclaw sessions history --limit 20

# 查看特定会话
openclaw sessions list --session main

4.2 定时任务（Cron）

OpenClaw 内置强大的定时任务功能，适合自动化工作流。

查看定时任务：

openclaw cron list

添加定时任务：

# 每天 7 点推送 AI 新闻
openclaw cron add \
  --name "AI 新闻推送" \
  --schedule "0 7 * * *" \
  --session isolated \
  --message "请搜索并整理今天 AI 领域最前沿的重要新闻，然后推送给我。"

# 每小时健康检查
openclaw cron add \
  --name "健康检查" \
  --schedule "0 * * * *" \
  --session main \
  --message "执行健康检查：openclaw doctor --fix"

定时任务配置示例：

{
  "jobs": [
    {
      "id": "health-check",
      "name": "每小时健康检查",
      "schedule": "0 * * * *",
      "sessionTarget": "isolated",
      "payload": {
        "kind": "agentTurn",
        "message": "执行健康检查并发送报告"
      },
      "delivery": {
        "channel": "feishu",
        "mode": "announce"
      }
    }
  ]
}

4.3 工具系统

OpenClaw 提供丰富的内置工具来增强交互能力。

浏览器控制：

# 打开网页
openclaw browser open https://example.com

# 执行搜索
openclaw browser search "OpenClaw tutorial"

# 截取快照
openclaw browser snapshot

Canvas（画布）：

# 推送内容到画布
openclaw canvas push --content "Hello from OpenClaw!"

# 重置画布
openclaw canvas reset

# 获取画布快照
openclaw canvas snapshot

Nodes（节点）：

# 拍照
openclaw nodes camera snap --output photo.jpg

# 获取位置
openclaw nodes location get

# 发送通知
openclaw nodes notify --title "标题" --body "内容"

4.4 技能系统（Skills）

OpenClaw 的技能系统允许你扩展功能，类似于插件机制。

查看已安装技能：

openclaw skills list

安装新技能：

# 从 ClawHub 安装
openclaw clawhub install weather

# 从本地安装
openclaw skills install /path/to/skill

可用技能列表：

五、高级配置与优化

5.1 模型配置与故障转移

OpenClaw 支持配置多个模型，实现故障自动转移，确保服务稳定性。

配置示例：

{
  "models": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    },
    "fallback": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  },
  "modelFailover": {
    "enabled": true,
    "maxRetries": 3,
    "retryDelay": 1000
  }
}

API 密钥配置：

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

# OpenAI
export OPENAI_API_KEY="sk-xxx"

5.2 性能优化

内存优化：

{
  "agent": {
    "maxMemory": "4GB",
    "sessionPruning": {
      "enabled": true,
      "maxAge": "24h",
      "maxSessions": 10
    }
  }
}

并发优化：

{
  "gateway": {
    "concurrency": {
      "maxAgents": 5,
      "maxChannels": 10
    }
  }
}

5.3 安全配置

DM 安全策略：

{
  "channels": {
    "discord": {
      "dmPolicy": "pairing",
      "allowFrom": ["123456789"],
      "rateLimit": {
        "window": "1m",
        "max": 10
      }
    }
  }
}

运行安全检查：

openclaw security audit --deep

5.4 远程访问配置

Tailscale 暴露：

# 启用 Tailscale Serve
openclaw gateway tailscale serve

# 启用 Funnel（公网访问）
openclaw gateway tailscale funnel

SSH 隧道：

# 创建隧道
ssh -N -L 18789:localhost:18789 user@host

六、常见问题与解决方案

6.1 安装问题

问题 1：Node.js 版本不兼容

错误信息：Error: The engine "node" is incompatible

解决方案：

# 检查版本
node --version

# 使用 nvm 安装正确版本
nvm install 22
nvm use 22

问题 2：权限错误

错误信息：Error: EACCES: permission denied

解决方案：

# 使用 sudo（不推荐）
sudo npm install -g openclaw

# 或配置 npm 前缀
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

6.2 配置问题

问题 1：飞书插件重复 ID 警告

错误信息：duplicate plugin id detected; later plugin may be overridden

原因：飞书插件在两个目录都被加载。

解决方案：

# 删除本地开发目录
rm -rf ~/.openclaw/extensions/feishu

# 或重命名插件 ID
# 在配置文件中修改

问题 2：通道连接失败

错误信息：Error: Channel connection failed

排查步骤：

# 1. 检查通道配置
openclaw doctor --channel feishu

# 2. 查看日志
openclaw gateway --verbose

# 3. 测试网络连接
curl https://open.feishu.cn

6.3 运行时问题

问题 1：内存不足

错误信息：JavaScript heap out of memory

解决方案：

# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=8192"

# 或在配置中设置
{
  "agent": {
    "maxMemory": "8GB"
  }
}

问题 2：模型调用失败

错误信息：Error: Model request failed

排查步骤：

# 1. 检查 API 密钥
echo $ANTHROPIC_API_KEY

# 2. 测试 API 连接
curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/messages

# 3. 查看详细错误
openclaw gateway --verbose

6.4 健康检查与诊断

运行完整诊断：

# 基本检查
openclaw doctor

# 详细检查
openclaw doctor --deep

# 修复已知问题
openclaw doctor --fix

诊断报告示例：

┌─────────────────────────────────────────┐
│ OpenClaw Doctor                         │
├─────────────────────────────────────────┤
│ 版本：v2026.2.9                         │
│ 状态：✅ 健康                           │
│ 安全：✅ 通过                           │
│ 插件：6 个已加载，0 错误                 │
│ 定时任务：3 个                          │
└─────────────────────────────────────────┘

七、进阶技巧与最佳实践

7.1 多代理配置

OpenClaw 支持配置多个独立的 AI 代理，针对不同场景分配不同模型。

配置示例：

{
  "agents": {
    "main": {
      "model": "claude-sonnet-4",
      "channels": ["feishu", "telegram"]
    },
    "research": {
      "model": "gpt-4o",
      "channels": ["discord"],
      "systemPrompt": "你是一个专业的研究助手..."
    },
    "coding": {
      "model": "claude-sonnet-4",
      "channels": ["slack"],
      "systemPrompt": "你是一个专业的编程助手..."
    }
  }
}

路由配置：

{
  "routing": {
    "rules": [
      {
        "channel": "discord",
        "agent": "coding"
      },
      {
        "channel": "slack",
        "agent": "research"
      }
    ]
  }
}

7.2 自定义技能开发

你可以编写 TypeScript 代码来创建自定义技能。

创建新技能：

// skills/my-weather/index.ts
import { Skill } from '@openclaw/sdk';

export default class MyWeatherSkill extends Skill {
  name = 'my-weather';
  description = '自定义天气查询技能';

  async getWeather(city: string): Promise<string> {
    const response = await fetch(
      `https://api.weather.example.com/${city}`
    );
    const data = await response.json();
    return `当前${city}天气：${data.temperature}°C，${data.condition}`;
  }
}

技能配置：

{
  "skills": {
    "my-weather": {
      "enabled": true,
      "config": {
        "apiKey": "your-api-key"
      }
    }
  }
}

7.3 自动化工作流

定时数据同步：

# 创建同步脚本
cat > ~/sync-data.sh << 'EOF'
#!/bin/bash
# 同步 Samba 服务器数据
smbclient -U xxx 用户名%xxx 密码 "//xxx.xxx.xxx.xxx/子目录" \
  -c "recurse; lcd ~/openclaw/data; prompt; mget 模型库"
EOF
chmod +x ~/sync-data.sh

Webhook 触发：

{
  "webhooks": [
    {
      "url": "/webhook/github",
      "events": ["push", "pull_request"],
      "action": "notify-agent"
    }
  ]
}

7.4 性能监控

设置监控：

# 查看资源使用
openclaw gateway --stats

# 导出诊断信息
openclaw doctor --export diagnostics.json

日志配置：

{
  "logging": {
    "level": "info",
    "format": "json",
    "output": "file",
    "path": "~/.openclaw/logs"
  }
}

7.5 数据备份与恢复

备份配置：

# 备份所有数据
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/

# 备份特定目录
cp -r ~/.openclaw/config backup/

恢复数据：

# 恢复配置
tar -xzvf openclaw-backup-20260212.tar.gz -C ~/

# 重启服务
openclaw gateway restart

八、使用场景与案例

8.1 个人 AI 助手

作为个人助理，处理日常消息、管理日程、回答问题。建议启用飞书/Telegram 通道，配置配对模式保护隐私，并设置定时健康检查。

8.2 团队协作工具

在团队 Slack/Discord 频道中，提供 AI 辅助功能。配置团队通道，设置多代理路由，启用群组规则，让团队成员可以通过 AI 助手查询文档、编写代码、生成报告。

8.3 自动化监控系统

监控系统状态，自动发送告警和报告。配置定时任务，设置健康检查，启用 Webhook 通知，每小时自动检查系统状态，有问题时立即通知。

8.4 知识库助手

构建个人或团队知识库，通过 AI 助手检索和问答。集成向量数据库，配置 RAG 技能，设置知识同步任务，AI 助手可以回答基于知识库的问题，提供准确信息。

九、未来展望

9.1 技术发展趋势

1. 多模态能力增强：更好的图像、音频、视频处理能力。
2. 边缘计算支持：在本地设备上运行更复杂的 AI 模型。
3. 标准化协议：MCP 等协议的普及，实现更好的工具互操作性。

9.2 生态系统发展

1. 更多通道支持：新增更多消息平台和工具集成。
2. 技能市场：ClawHub 技能市场的繁荣。
3. 社区贡献：更多开源技能和模板的涌现。

9.3 开发者机会

1. 开发新技能：针对特定领域的技能开发。
2. 集成新通道：为新平台开发通道支持。
3. 工具优化：性能优化和用户体验改进。

结语

OpenClaw 作为一个开源的跨平台 AI 助手框架，为用户提供了一个强大、灵活且隐私安全的 AI 助手解决方案。通过本文的介绍，相信你已经对 OpenClaw 有了全面的了解，并能够顺利配置和使用它。

关键要点总结：

1. 安装简单：一行命令即可安装。
2. 配置灵活：支持多种通道和模型。
3. 功能丰富：定时任务、工具系统、技能扩展。
4. 安全可控：本地运行，数据完全可控。
5. 社区活跃：Discord 社区支持，持续更新。

建议：

1. 从简单开始：先配置一个通道，熟悉基本功能。
2. 逐步扩展：根据需要添加更多通道和技能。
3. 关注安全：合理配置 DM 策略，保护隐私。
4. 善用社区：遇到问题可以在 Discord 社区求助。
5. 持续学习：关注官方文档和更新日志。

下一步行动：

1. 安装 OpenClaw 并运行初始配置。
2. 配置一个消息通道（如飞书）。
3. 设置定时健康检查任务。
4. 探索和安装有用的技能。
5. 根据需求定制自己的 AI 助手。

附录

附录 A：常用命令速查表

附录 B：配置文件完整示例

{
  "version": "2026.2.9",
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1",
    "verbose": false
  },
  "models": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "maxTokens": 8192,
      "temperature": 0.7
    }
  },
  "modelFailover": {
    "enabled": true,
    "maxRetries": 3
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}"
    }
  },
  "skills": {
    "enabled": true,
    "installDir": "~/.openclaw/skills"
  },
  "logging": {
    "level": "info",
    "format": "json",
    "path": "~/.openclaw/logs"
  },
  "agent": {
    "maxMemory": "4GB",
    "sessionPruning": {
      "enabled": true,
      "maxAge": "24h"
    }
  }
}

附录 C：参考资源链接

官方资源

• GitHub：https://github.com/openclaw/openclaw
• 官网：https://openclaw.ai
• 文档：https://docs.openclaw.ai
• Discord：discord.gg/clawd