openclaw使用指南
OpenClaw 完整介绍文档
一个强大的 AI 代理运行时框架，让 AI 助手真正拥有自主工作能力
文档版本: 1.0
最后更新: 2026-03-11
适用版本: OpenClaw v2.x+
目录
1. OpenClaw 简介
1.1 什么是 OpenClaw
OpenClaw 是一个开源的 AI 代理运行时框架，专为构建自主、多通道、可协作的 AI 助手系统而设计。它不仅仅是一个聊天机器人框架，更是一个完整的 AI 代理生态系统，让 AI 能够真正"生活"在你的数字环境中，持续工作、学习和成长。
OpenClaw 的核心理念是：AI 代理应该是持久的、有记忆的、可协作的，并且能够无缝融入现有的通信渠道。
1.2 核心定位和目标用户
核心定位： - AI 代理的"操作系统" - 多代理协作的基础设施 - 通信渠道与 AI 模型的桥梁
目标用户： - 开发者：构建自定义 AI 助手和自动化工作流 - 团队：为 Telegram、Discord 等群组部署专属 AI 助手 - 企业：搭建内部 AI 代理系统，实现智能客服、知识管理等 - 研究者：探索多代理协作、AI 记忆系统等前沿课题
1.3 主要特点和优势
| 特点 | 说明 | 优势 |
|---|---|---|
| 多渠道支持 | Telegram、Discord、WebChat 等 | 一处部署，多平台服务 |
| 子代理系统 | 支持多代理并发协作 | 复杂任务分工处理 |
| 插件架构 | 技能（Skills）系统 | 功能无限扩展 |
| 记忆系统 | 持久化会话和上下文 | AI 拥有长期记忆 |
| ⏰ 任务调度 | 内置 cron 调度器 | 定时任务自动化 |
| 安全隔离 | 工作空间独立 | 代理间数据隔离 |
| 易于部署 | npm 一键安装 | 快速上手 |
2. 核心功能
2.1 多渠道支持
OpenClaw 支持多种通信渠道，让 AI 助手可以在用户最常用的平台上提供服务。
支持的渠道：
# config.yaml 中的渠道配置示例
channels:
telegram:
enabled:true
token:"YOUR_BOT_TOKEN"
allowedGroups:[-5017202758]
discord:
enabled:true
token:"YOUR_BOT_TOKEN"
allowedGuilds:["guild_id_1","guild_id_2"]
webchat:
enabled:true
port:3000
auth:false# 可选认证
渠道特性： - Telegram：支持群组、私聊、频道消息 - Discord：支持服务器、频道、私信 - WebChat：内置 Web 界面，支持自定义部署 - 扩展性：可通过插件添加新渠道（Slack、WhatsApp 等）
2.2 子代理系统
子代理系统是 OpenClaw 的核心创新之一，允许主代理动态创建和管理多个专用子代理。
子代理应用场景：
主代理 (大龙虾)
├── 小龙虾-PM (文档处理专家)
├── 小龙虾-FS (全栈开发专家)
├── 小龙虾-QA (测试质量专家)
└── 小龙虾-VL (视觉语言专家)
子代理创建示例：
// 通过 API 创建子代理
{
"action":"sessions_spawn",
"session":"agent:dalongxia:subagent:pm-001",
"model":"qwen3.5-plus",
"cwd":"/Users/Jackpot/AI/workspace-pm-xiaolongxia/",
"message":"你是小龙虾-PM，专注于文档处理..."
}
子代理特性： - 独立工作空间 - 独立会话上下文 - 可指定不同模型 - 支持深度嵌套（子代理可再创建子代理） - 自动结果回传
2.3 插件架构（Skills 系统）
OpenClaw 的插件系统称为"Skills"，是预定义的任务处理模块。
内置 Skills 示例：
| Skill 名称 | 功能 | 触发条件 |
|---|---|---|
github |
GitHub 操作（issues、PRs、CI） | 涉及 GitHub 任务 |
weather |
天气查询 | 询问天气相关 |
healthcheck |
安全审计和系统检查 | 安全相关请求 |
clawhub |
技能市场操作 | 安装/更新技能 |
skill-creator |
创建和编辑 Skills | 技能开发任务 |
gh-issues |
自动处理 GitHub Issues | Issues 监控任务 |
Skill 结构：
skills/
└── weather/
├── SKILL.md # 技能描述和触发规则
├── index.js # 主逻辑
├── config.yaml # 技能配置
└── scripts/ # 辅助脚本
SKILL.md 示例：
# SKILL.md - Weather Skill
## Description
Get current weather and forecasts via wttr.in or Open-Meteo.
## Usage
Triggered when user asks about weather, temperature, or forecasts.
## Commands
-/weather [location]
-/forecast [location] [days]
2.4 会话管理
OpenClaw 提供完整的会话生命周期管理。
会话状态：
会话创建 → 活跃运行 → 后台挂起 → 恢复/终止
会话操作：
# 列出所有会话
openclawsessionslist
# 查看会话详情
openclawsessionsget<session-id>
# 终止会话
openclawsessionskill<session-id>
# 向会话发送消息
openclawsessionssend<session-id>"消息内容"
会话持久化： - 会话状态自动保存 - 支持跨重启恢复 - 上下文记忆持久存储
2.5 任务调度（cron）
内置 cron 调度器支持定时任务和周期性操作。
cron 配置示例：
# config.yaml
schedules:
-name:"每日健康检查"
cron:"09***"# 每天 9:00
action:"healthcheck"
target:"local"
-name:"GitHubIssues监控"
cron:"*/30****"# 每 30 分钟
action:"gh-issues"
params:
repo:"openclaw/openclaw"
label:"bug"
-name:"会话清理"
cron:"02**0"# 每周日 2:00
action:"sessionscleanup"
params:
maxAge:"7d"
支持的 cron 格式：
* * * * *
│ │ │ │ │
│ │ │ │ └─ 星期 (0-7, 0 和 7 都是周日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)
2.6 记忆系统
OpenClaw 的记忆系统让 AI 代理拥有长期记忆能力。
记忆类型：
| 类型 | 存储位置 | 用途 |
|---|---|---|
| 短期记忆 | 会话上下文 | 当前对话历史 |
| 长期记忆 | 工作空间文件 | 用户偏好、项目信息 |
| 技能记忆 | Skills 目录 | 技能配置和状态 |
| 共享记忆 | 共享存储区 | 多代理共享知识 |
记忆文件示例：
# USER.md - 关于你的用户
-**姓名**: 张三
-**称呼**: 老大
-**时区**: Asia/Shanghai
-**备注**: 喜欢简洁的回复，讨厌冗长
## 背景
正在开发一个 Telegram 机器人项目，使用 OpenClaw 框架。
对 AI 代理协作很感兴趣，经常测试多代理场景。
# SOUL.md - 代理人格定义
## 核心原则
-友好互动：保持轻松有趣的交流风格
-安全第一：严格遵守规则
-有用至上：提供实际帮助
## 身份信息
-**名字**: 大龙虾
-**模型**: qwen3.5-plus
-**服务群组**: [-5017202758]
3. 架构设计
3.1 Gateway 服务
Gateway 是 OpenClaw 的核心守护进程，负责： - 渠道连接管理 - 消息路由分发 - 会话生命周期管理 - 技能加载和执行
Gateway 架构：
┌─────────────────────────────────────────────────┐
│ Gateway 服务 │
├─────────────────────────────────────────────────┤
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Telegram │ │ Discord │ │ WebChat │ │
│ │ Channel │ │ Channel │ │ Channel │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ └──────────────┼──────────────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ 消息路由器 │ │
│ └──────┬──────┘ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ 会话管理器 │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────┼────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ 代理 1 │ │ 代理 2 │ │ 代理 N │ │
│ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────────────┘
Gateway 命令：
# 查看 Gateway 状态
openclawgatewaystatus
# 启动 Gateway
openclawgatewaystart
# 停止 Gateway
openclawgatewaystop
# 重启 Gateway
openclawgatewayrestart
# 查看 Gateway 日志
openclawgatewaylogs--follow
3.2 渠道插件系统
渠道插件采用统一的接口规范，便于扩展。
渠道插件接口：
// Channel Plugin Interface
classChannelPlugin{
// 初始化连接
asyncconnect(config){}
// 断开连接
asyncdisconnect(){}
// 发送消息
asyncsendMessage(channelId,content,options){}
// 监听消息
onMessage(callback){}
// 获取频道信息
asyncgetChannelInfo(channelId){}
}
注册新渠道：
// 在 config.yaml 中注册
channels:
custom:
enabled:true
plugin:"./plugins/my-custom-channel.js"
config:
apiKey:"xxx"
endpoint:"https://api.example.com"
3.3 子代理运行时
子代理在独立的 Node.js 进程中运行，确保隔离性。
子代理运行时架构：
┌────────────────────────────────────────┐
│ 主代理进程 │
│ (Gateway + 主代理会话) │
└───────────────┬────────────────────────┘
│ (进程间通信)
▼
┌────────────────────────────────────────┐
│ 子代理进程 1 │
│ - 独立 Node.js 运行时 │
│ - 独立工作空间 │
│ - 独立会话上下文 │
│ - 独立技能加载 │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ 子代理进程 2 │
│ (可继续创建子代理，支持嵌套) │
└────────────────────────────────────────┘
进程间通信： - 使用 ACP（Agent Communication Protocol） - 消息队列保证可靠性 - 支持流式响应
3.4 工作空间隔离
每个代理拥有独立的工作空间，确保数据和配置隔离。
工作空间结构：
workspace-dalongxia/
├── SOUL.md # 代理人格定义
├── AGENTS.md # 工作空间说明
├── IDENTITY.md # 代理身份信息
├── USER.md # 用户信息
├── TOOLS.md # 本地工具配置
├── skills/ # 自定义技能
├── memories/ # 长期记忆
├── sessions/ # 会话数据
└── config.yaml # 工作空间配置
工作空间隔离策略： - 文件系统隔离：每个工作空间独立目录 - 配置隔离：独立的 config.yaml - 会话隔离：独立的会话存储 - 技能隔离：可加载自定义技能
4. 安装与配置
4.1 系统要求
最低要求： - Node.js v18.0.0+（推荐 v22+） - npm v9.0.0+ - 内存：512MB+ - 磁盘：1GB+ 可用空间
推荐配置： - Node.js v22 LTS - 内存：2GB+ - CPU：2 核+ - 网络：稳定互联网连接
4.2 安装步骤
全局安装：
# 使用 npm 全局安装
npminstall-gopenclaw
# 验证安装
openclaw--version
# 查看帮助
openclaw--help
使用 nvm 管理 Node 版本：
# 安装指定 Node 版本
nvminstall22
nvmuse22
# 安装 OpenClaw
npminstall-gopenclaw
从源码安装（开发模式）：
# 克隆仓库
gitclonehttps://github.com/openclaw/openclaw.git
cdopenclaw
# 安装依赖
npminstall
# 链接到全局
npmlink
# 验证
openclaw--version
4.3 基础配置
创建配置文件：
# 初始化配置目录
mkdir-p~/.openclaw
cd~/.openclaw
# 创建基础配置
openclawinit
config.yaml 完整示例：
# OpenClaw 主配置文件
# 通用设置
general:
language:zh-CN
timezone:Asia/Shanghai
logLevel:info
dataDir:~/.openclaw/data
# 模型配置
models:
default:bailian/qwen3.5-plus
fallback:openai/gpt-4o
providers:
bailian:
apiKey:${BAILIAN_API_KEY}
endpoint:https://dashscope.aliyuncs.com
openai:
apiKey:${OPENAI_API_KEY}
# 渠道配置
channels:
telegram:
enabled:true
token:${TELEGRAM_BOT_TOKEN}
allowedGroups:
--5017202758
allowedUsers:[]# 空表示允许所有
maxMessageLength:4096
discord:
enabled:false
token:${DISCORD_BOT_TOKEN}
allowedGuilds:[]
intents:
-GUILDS
-GUILD_MESSAGES
-DIRECT_MESSAGES
webchat:
enabled:true
port:3000
host:0.0.0.0
auth:false
cors:true
# 会话配置
sessions:
maxConcurrent:10
maxDuration:24h
persistHistory:true
historyLimit:100
# 调度器配置
scheduler:
enabled:true
timezone:Asia/Shanghai
maxConcurrentJobs:5
# 安全配置
security:
allowlistMode:false
rateLimit:
enabled:true
requestsPerMinute:60
auditLog:true
环境变量配置：
# .env 文件示例
BAILIAN_API_KEY=sk-xxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxx
TELEGRAM_BOT_TOKEN=123456:ABC-xxxxxxxx
DISCORD_BOT_TOKEN=xxxxxxxx
4.4 渠道配置
Telegram 渠道配置：
channels:
telegram:
enabled:true
token:${TELEGRAM_BOT_TOKEN}
# 允许的群组（空数组表示允许所有）
allowedGroups:
--5017202758
--1234567890
# 允许的用户（空数组表示允许所有）
allowedUsers:
-123456789
# 消息设置
maxMessageLength:4096
parseMode:Markdown
# 回复设置
replyToMessages:true
mentionReplies:true
获取 Telegram Bot Token： 1. 在 Telegram 中搜索 @BotFather 2. 发送 /newbot 创建新机器人 3. 按提示设置名称和用户名 4. 获取 API Token
Discord 渠道配置：
channels:
discord:
enabled:true
token:${DISCORD_BOT_TOKEN}
# 允许的服务器
allowedGuilds:
-"123456789012345678"
# 需要的 Intents
intents:
-GUILDS
-GUILD_MESSAGES
-GUILD_MEMBERS
-DIRECT_MESSAGES
# 前缀命令
prefix:"!"
获取 Discord Bot Token： 1. 访问 https://discord.com/developers/applications 2. 创建新应用 3. 在 "Bot" 页面创建机器人 4. 复制 Token 5. 在 "OAuth2" 页面生成邀请链接，添加机器人到服务器
5. 使用指南
5.1 基本命令
Gateway 管理：
# 查看 Gateway 状态
openclawgatewaystatus
# 输出示例：
# Gateway: running
# Uptime: 2d 5h 32m
# Active Sessions: 3
# Channels: telegram (connected), webchat (connected)
# 启动 Gateway
openclawgatewaystart
# 输出：Gateway started successfully
# 停止 Gateway
openclawgatewaystop
# 输出：Gateway stopped
# 重启 Gateway
openclawgatewayrestart
# 输出：Gateway restarted successfully
# 查看实时日志
openclawgatewaylogs--follow
# 查看最近 100 行日志
openclawgatewaylogs--lines100
会话管理：
# 列出所有活跃会话
openclawsessionslist
# 列出所有会话（包括已停止的）
openclawsessionslist--all
# 查看会话详情
openclawsessionsgetagent:dalongxia:main
# 向会话发送消息
openclawsessionssendagent:dalongxia:main"你好，请处理这个任务"
# 终止会话
openclawsessionskillagent:dalongxia:subagent:xxx
# 导出会话历史
openclawsessionsexportagent:dalongxia:main--output./history.json
5.2 子代理创建
通过 API 创建子代理：
// 在代码中创建子代理
constresponse=awaitfetch('http://localhost:3000/api/sessions/spawn',{
method:'POST',
headers:{'Content-Type':'application/json'},
body:JSON.stringify({
session:'agent:dalongxia:subagent:pm-001',
model:'qwen3.5-plus',
cwd:'/Users/Jackpot/AI/workspace-pm-xiaolongxia/',
message:'你是小龙虾 -PM，专注于文档处理...',
skills:['skill-creator','github']
})
});
通过 CLI 创建子代理：
# 创建子代理
openclawsessionsspawn\
--session"agent:dalongxia:subagent:pm-001"\
--model"qwen3.5-plus"\
--cwd"/Users/Jackpot/AI/workspace-pm-xiaolongxia/"\
--message"你是小龙虾-PM，专注于文档处理..."
子代理配置示例：
# 子代理配置文件
subagents:
pm-xiaolongxia:
name:小龙虾-PM
description:文档处理专家
workspace:/Users/Jackpot/AI/workspace-pm-xiaolongxia/
model:qwen3.5-plus
skills:
-skill-creator
-github
autoSpawn:false# 不自动创建
fs-xiaolongxia:
name:小龙虾-FS
description:全栈开发专家
workspace:/Users/Jackpot/AI/workspace-fs-xiaolongxia/
model:qwen3.5-plus
skills:
-github
-healthcheck
5.3 会话管理
会话状态流转：
[创建] → [活跃] → [等待] → [活跃] → [完成/终止]
↑ ↓
└──────────┘
会话操作最佳实践：
# 1. 创建会话时指定清晰的任务
openclawsessionsspawn\
--session"agent:xxx:task-001"\
--message"请分析这个 GitHub 仓库的 issues..."
# 2. 监控会话状态
openclawsessionslist--statusrunning
# 3. 需要时与会话交互
openclawsessionssend"agent:xxx:task-001""请优先处理 bug 类 issues"
# 4. 完成后清理
openclawsessionskill"agent:xxx:task-001"
5.4 文件操作
在工作空间内操作文件：
# 读取文件
openclawfsread./docs/readme.md
# 写入文件
openclawfswrite./docs/new-doc.md--content"内容..."
# 编辑文件（精确替换）
openclawfsedit./docs/readme.md\
--old"旧文本"\
--new"新文本"
# 列出目录
openclawfslist./docs/
# 复制文件
openclawfscopy./src/file.js./backup/file.js
# 删除文件
openclawfsdelete./temp/file.js
在代理代码中操作文件：
// 使用内置工具
awaittools.read({path:'./docs/readme.md'});
awaittools.write({path:'./docs/new.md',content:'内容'});
awaittools.edit({
path:'./docs/readme.md',
oldText:'旧文本',
newText:'新文本'
});
6. 高级功能
6.1 插件开发
创建自定义 Skill：
# 创建技能目录
mkdir-pskills/my-custom-skill
cdskills/my-custom-skill
# 创建 SKILL.md
cat>SKILL.md<< 'EOF'
# SKILL.md - My Custom Skill
## Description
描述技能的功能和用途。
## Usage
说明触发条件和使用方法。
## Commands
- /command1 [args]
- /command2 [args]
EOF
# 创建主逻辑
cat>index.js<< 'EOF'
module.exports = {
name: 'my-custom-skill',
async execute(context, params) {
// 技能逻辑
const result = await doSomething(params);
return result;
},
async validate(context) {
// 验证是否应该触发此技能
return context.message.includes('关键词');
}
};
EOF
Skill 注册：
# config.yaml
skills:
enabled:
-my-custom-skill
-github
-weather
paths:
-./skills# 自定义技能目录
-~/.openclaw/skills# 全局技能目录
6.2 自定义渠道
实现自定义渠道插件：
// plugins/slack-channel.js
const{ChannelPlugin}=require('openclaw');
classSlackChannelextendsChannelPlugin{
constructor(config){
super();
this.config=config;
this.client=null;
}
asyncconnect(){
// 初始化 Slack 客户端
this.client=newWebClient(this.config.token);
console.log('Slack channel connected');
}
asyncdisconnect(){
// 清理连接
this.client=null;
}
asyncsendMessage(channelId,content,options){
// 发送消息到 Slack
returnawaitthis.client.chat.postMessage({
channel:channelId,
text:content,
...options
});
}
onMessage(callback){
// 监听消息
this.client.on('message',callback);
}
}
module.exports=SlackChannel;
6.3 ACP（Agent Communication Protocol）
ACP 消息格式：
{
"type":"message",
"from":"agent:dalongxia:main",
"to":"agent:dalongxia:subagent:pm-001",
"id":"msg-001",
"timestamp":"2026-03-11T17:00:00Z",
"payload":{
"action":"task",
"content":"请编写文档",
"priority":"high",
"context":{
"workspace":"/Users/Jackpot/AI/workspace-pm-xiaolongxia/",
"deadline":"2026-03-11T18:00:00Z"
}
},
"metadata":{
"traceId":"trace-001",
"spanId":"span-001"
}
}
ACP 消息类型：
| 类型 | 用途 | 示例 |
|---|---|---|
message |
普通消息 | 任务分配、查询 |
command |
命令执行 | 启动、停止、重启 |
response |
响应消息 | 任务完成、结果返回 |
event |
事件通知 | 状态变更、错误 |
stream |
流式数据 | 实时日志、进度 |
6.4 记忆系统使用
写入长期记忆：
// 写入用户信息
awaittools.write({
path:'./USER.md',
content:`# USER.md
- **姓名**: 张三
- **偏好**: 简洁回复
- **项目**: Telegram 机器人开发
`
});
// 写入代理人格
awaittools.write({
path:'./SOUL.md',
content:`# SOUL.md
## 核心原则
- 友好、专业、高效
## 身份
- 名字：助手
- 专长：文档处理
`
});
读取记忆：
// 读取用户信息
constuser=awaittools.read({path:'./USER.md'});
console.log(user.content);
// 读取代理配置
constsoul=awaittools.read({path:'./SOUL.md'});
console.log(soul.content);
记忆更新策略：
// 增量更新记忆
asyncfunctionupdateUserPreference(userId,preference){
constuserFile=awaittools.read({path:'./USER.md'});
constupdated=updateContent(userFile.content,preference);
awaittools.write({path:'./USER.md',content:updated});
}
7. 最佳实践
7.1 工作空间管理
工作空间组织：
AI/
├── workspace-dalongxia/ # 主代理工作空间
│ ├── SOUL.md
│ ├── USER.md
│ └── ...
├── workspace-pm-xiaolongxia/ # PM 子代理
│ ├── docs/
│ └── ...
├── workspace-fs-xiaolongxia/ # FS 子代理
│ ├── src/
│ └── ...
└── workspace-qa-xiaolongxia/ # QA 子代理
├── tests/
└── ...
工作空间命名规范： - 使用小写字母和连字符 - 包含代理角色标识 - 保持语义清晰
✅ workspace-pm-xiaolongxia
✅ workspace-fs-xiaolongxia
❌ workspace1
❌ Workspace_PM
7.2 子代理协作模式
任务分解模式：
主代理
↓ 接收复杂任务
↓ 分解为子任务
├──→ 子代理-PM: 文档编写
├──→ 子代理-FS: 代码实现
└──→ 子代理-QA: 测试验证
↓ 汇总结果
↓ 返回最终结果
子代理通信示例：
// 主代理创建子代理并分配任务
constpmAgent=awaitspawnSubagent({
session:'agent:main:subagent:pm',
message:'请编写项目文档',
workspace:'./workspace-pm/'
});
constfsAgent=awaitspawnSubagent({
session:'agent:main:subagent:fs',
message:'请实现核心功能',
workspace:'./workspace-fs/'
});
// 等待子代理完成
const[pmResult,fsResult]=awaitPromise.all([
waitForCompletion(pmAgent),
waitForCompletion(fsAgent)
]);
// 汇总结果
returncombineResults(pmResult,fsResult);
7.3 会话持久化策略
会话保存配置：
sessions:
persistHistory:true
historyLimit:100# 保留最近 100 条消息
autoSave:true
saveInterval:60s# 每 60 秒自动保存
# 会话超时
idleTimeout:24h
maxDuration:7d
# 恢复策略
recovery:
enabled:true
maxRetries:3
retryDelay:5s
会话备份：
# 定期备份会话数据
openclawsessionsbackup--output./backups/sessions-$(date+%Y%m%d).tar.gz
# 恢复会话
openclawsessionsrestore--input./backups/sessions-20260311.tar.gz
7.4 安全配置
访问控制：
security:
# 白名单模式
allowlistMode:true
allowedUsers:
-123456789
-987654321
# 速率限制
rateLimit:
enabled:true
requestsPerMinute:60
burstSize:10
# 审计日志
auditLog:
enabled:true
path:./logs/audit.log
retention:30d
# 敏感操作确认
requireConfirmation:
-sessions_kill
-fs_delete
-gateway_restart
API 密钥管理：
# 使用环境变量存储密钥
exportBAILIAN_API_KEY="sk-xxx"
exportTELEGRAM_BOT_TOKEN="xxx"
# 在 config.yaml 中引用
models:
bailian:
apiKey:${BAILIAN_API_KEY}
网络安全：
# 限制监听地址
webchat:
host:127.0.0.1# 仅本地访问
port:3000
# 启用 HTTPS
https:
enabled:true
cert:./certs/cert.pem
key:./certs/key.pem
8. 常见问题
8.1 安装问题
Q: npm install 失败，提示权限错误
# 解决方案 1: 使用 sudo
sudonpminstall-gopenclaw
# 解决方案 2: 修复 npm 权限（推荐）
mkdir~/.npm-global
npmconfigsetprefix'~/.npm-global'
echo'export PATH=~/.npm-global/bin:$PATH'>>~/.zshrc
source~/.zshrc
npminstall-gopenclaw
Q: Node.js 版本不兼容
# 检查 Node 版本
node--version
# 使用 nvm 切换到推荐版本
nvminstall22
nvmuse22
nvmaliasdefault22
# 重新安装
npminstall-gopenclaw
Q: 依赖安装缓慢或失败
# 使用国内镜像
npmconfigsetregistryhttps://registry.npmmirror.com
# 清理缓存后重新安装
npmcacheclean--force
npminstall-gopenclaw
8.2 渠道配置问题
Q: Telegram 机器人无法连接
# 检查 Token 是否正确
echo$TELEGRAM_BOT_TOKEN
# 验证机器人是否活跃
curl"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"
# 检查群组权限
# 确保机器人已添加到群组并有读取消息权限
Q: Discord 机器人收不到消息
# 检查 intents 配置
discord:
intents:
-GUILDS
-GUILD_MESSAGES
-MESSAGE_CONTENT# 需要启用此 intent 才能读取消息内容
Q: WebChat 无法访问
# 检查端口是否被占用
lsof-i:3000
# 检查防火墙
sudoufwallow3000
# 查看日志
openclawgatewaylogs--grepwebchat
8.3 子代理会话问题
Q: 子代理无法创建
# 检查工作空间是否存在
ls-la/Users/Jackpot/AI/workspace-pm-xiaolongxia/
# 创建缺失的目录
mkdir-p/Users/Jackpot/AI/workspace-pm-xiaolongxia/
# 检查权限
chmod755/Users/Jackpot/AI/workspace-pm-xiaolongxia/
# 查看错误日志
openclawgatewaylogs--grep"subagent"
Q: 子代理无响应
# 检查子代理状态
openclawsessionslist--statusrunning
# 查看子代理日志
openclawsessionslogsagent:dalongxia:subagent:xxx
# 重启子代理
openclawsessionskillagent:dalongxia:subagent:xxx
openclawsessionsspawn--session"agent:dalongxia:subagent:xxx"...
Q: 子代理结果未返回
// 检查 ACP 连接
// 确保主代理和子代理之间的通信通道正常
// 增加超时时间
{
timeout:300000,// 5 分钟
retryAttempts:3
}
8.4 性能优化
Q: Gateway 内存占用过高
# 优化会话配置
sessions:
maxConcurrent:5# 限制并发会话数
historyLimit:50# 减少历史记录
idleTimeout:1h# 缩短空闲超时
# 优化模型配置
models:
default:qwen3.5-plus
cache:
enabled:true
maxSize:100MB
Q: 消息处理延迟高
# 检查系统资源
top
htop
# 优化日志级别
# config.yaml
general:
logLevel:warn# 减少日志输出
# 增加 Worker 数量（如果支持）
workers:4
Q: 文件操作缓慢
# 使用 SSD 存储
# 确保工作空间在 SSD 上
# 减少不必要的文件读写
# 批量操作代替单个操作
# 使用缓存
skills:
cache:
enabled:true
ttl:3600# 1 小时缓存
9. 资源链接
官方资源
| 资源 | 链接 | 说明 |
|---|---|---|
| 官方文档 | https://docs.openclaw.ai | 完整 API 文档和教程 |
| GitHub | https://github.com/openclaw/openclaw | 源代码和 Issues |
| Discord 社区 | https://discord.com/invite/clawd | 用户交流和支援 |
| ClawHub | https://clawhub.com | 技能市场和插件 |
学习资源
- 入门教程: https://docs.openclaw.ai/getting-started
- API 参考: https://docs.openclaw.ai/api-reference
- 技能开发: https://docs.openclaw.ai/skills/creating
- 最佳实践: https://docs.openclaw.ai/best-practices
社区资源
- 示例项目: https://github.com/openclaw/examples
- 技能仓库: https://github.com/openclaw/skills
- 社区插件: https://github.com/topics/openclaw-plugin
技术支持
- Issues: https://github.com/openclaw/openclaw/issues
- Discussions: https://github.com/openclaw/openclaw/discussions
- 邮件列表: openclaw-support@groups.io
附录
A. 命令速查表
# Gateway 管理
openclawgatewaystart|stop|restart|status|logs
# 会话管理
openclawsessionslist|get|spawn|kill|send|export|backup|restore
# 文件操作
openclawfsread|write|edit|list|copy|delete
# 技能管理
openclawskillslist|install|update|remove
# 配置管理
openclawconfigget|set|export|import
# 系统信息
openclaw--version
openclaw--help
openclawdoctor# 诊断工具
B. 配置文件模板
完整 config.yaml 模板请参考官方文档： https://docs.openclaw.ai/configuration
浙公网安备 33010602011771号