文章目录

1. 安装与配置

1.1 环境要求

  • 操作系统：Windows 10/11（64位）、Linux（CentOS 7+/Ubuntu 18.04+）
  • 权限：管理员/root 权限（部分操作需）
  • 网络：可访问公网（用于下载安装包、验证API密钥）

1.2 安装步骤

  1. 下载安装包：
  2. 安装执行：
    • Windows：双击安装包，跟随向导完成（默认安装路径 C:\Program Files\OpenClaw）
    • Linux：chmod +x openclaw-installer.run && ./openclaw-installer.run
  3. 安装验证： 
    openclaw status
    输出 "OpenClaw is installed and ready" 即为安装成功。

1.3 初始化配置

1.3.1 新手引导（首次安装）
openclaw onboard

跟随交互式引导完成：

  • 语言设置（中文/英文）
  • 基础服务路径配置
  • 默认模型选择
1.3.2 API密钥配置
全局配置
# 交互式配置Web类服务密钥（Brave Search等）
openclaw configure --section web
# 直接设置配置项（推荐批量配置使用）
openclaw config set api.key=xxx-xxxx-xxxx
openclaw config set model.gpt5.token=sk-xxxx
模型专用令牌配置
openclaw models auth setup-token

按提示输入对应模型（GPT-5、Claude等）的API令牌，完成认证。

1.3.3 通信渠道配置
# 添加飞书/WhatsApp等通信渠道
openclaw channels add feishu
openclaw channels add whatsapp

2. 基础服务管理

2.1 OpenClaw 核心服务

命令 功能说明
openclaw start 启动OpenClaw主服务
openclaw stop 停止OpenClaw主服务
openclaw restart 重启OpenClaw主服务
openclaw status 查看主服务运行状态
openclaw status --all 查看所有组件运行状态，生成基础诊断报告

2.2 Gateway 网关服务

网关是OpenClaw与外部渠道（飞书、WhatsApp）通信的核心组件：

命令 功能说明
openclaw gateway start 启动网关服务
openclaw gateway stop 停止网关服务
openclaw gateway restart 重启网关服务
openclaw gateway status 查看网关运行状态
openclaw gateway install 将网关安装为系统服务（开机自启）
openclaw gateway uninstall 卸载网关系统服务

3. 核心功能操作

3.1 文件操作

命令 功能说明 示例
openclaw read <文件路径> 读取指定文件内容 openclaw read C:\data\config.json
openclaw write <文件路径> "内容" 向指定文件写入内容（覆盖原有内容） openclaw write C:\logs\test.log "操作时间：2024-01-01"

3.2 任务与进程管理

命令 功能说明 示例
openclaw exec "命令" 执行自定义系统命令 openclaw exec "ipconfig /all"
openclaw process list 列出OpenClaw关联的所有进程 -
openclaw sessions_spawn --task "任务描述" 调用子代理执行指定任务 openclaw sessions_spawn --task "批量处理飞书消息"

3.3 消息测试

用于验证渠道通信能力，支持多类型目标：

# 基础用法
openclaw message send --target <目标标识> --message "消息内容"

# 示例1：向飞书部门ID发送消息
openclaw message send --target "ou_123456" --message "系统运维通知：网关已重启"

# 示例2：向WhatsApp号码发送消息
openclaw message send --target "+8613800138000" --message "测试消息：Hello OpenClaw"

4. 渠道管理

4.1 登录与登出

# 登录飞书（需扫码/令牌验证）
openclaw channels login feishu
# 登录WhatsApp（自动触发扫码验证）
openclaw channels login whatsapp
# 登出指定渠道
openclaw channels logout feishu

4.2 状态与配对

命令 功能说明 示例
openclaw channels status 查看所有渠道连接状态 -
openclaw channels status --probe 深度检测渠道连通性（含网络/权限） -
openclaw pairing list <channel> 查看指定渠道待审批配对请求 openclaw pairing list feishu
openclaw pairing approve <channel> <code> 批准配对请求 openclaw pairing approve feishu 886699

5. 高级功能

5.1 技能管理（Skills）

技能是OpenClaw的扩展能力组件，详情参考：https://sophnet.com/docs/component/openclawSkills.html

命令 功能说明 示例
openclaw skills list 列出已安装/可用技能 -
openclaw skills install <技能名> 安装官方技能 openclaw skills install feishu-auto-reply
openclaw skills install <自定义技能URL> 安装第三方自定义技能 openclaw skills install https://sophnet.com/skills/ocr-skill.zip
openclaw skills uninstall <技能名> 卸载指定技能 openclaw skills uninstall ocr-skill
openclaw skills update <技能名> 更新指定技能 openclaw skills update feishu-auto-reply
openclaw skills enable <技能名> 启用技能 openclaw skills enable feishu-auto-reply
openclaw skills disable <技能名> 禁用技能 openclaw skills disable feishu-auto-reply
技能开发与部署说明
  • 技能基于Python/Go开发，需遵循OpenClaw技能开发规范（参考官网文档）
  • 自定义技能打包为.zip格式，包含主程序、依赖文件、配置清单
  • 技能部署后可通过 openclaw exec "skill run <技能名>" 触发执行

5.2 子代理调用进阶

# 指定代理类型启动子代理
openclaw sessions_spawn --type feishu --task "同步部门通讯录"

# 设置子代理超时时间
openclaw sessions_spawn --task "数据导出" --timeout 3600

# 批量启动子代理任务
openclaw sessions_spawn --batch ./task-list.json

其中 task-list.json 格式示例：

[
  {"task": "处理用户反馈", "type": "whatsapp", "timeout": 1800},
  {"task": "生成日报", "type": "feishu", "timeout": 2400}
]

6. 日志与诊断

6.1 日志查看

命令 功能说明
openclaw logs --follow 实时跟踪日志输出（类似Linux tail -f）
openclaw logs --limit 100 查看最近100条日志
openclaw logs --since "2024-01-01 00:00:00" 查看指定时间后的日志
openclaw logs --level ERROR 仅查看错误级别日志（支持DEBUG/INFO/WARN/ERROR/FATAL）

6.2 诊断工具

命令 功能说明
openclaw doctor 运行全量诊断（含服务、网络、配置、模型）
openclaw doctor --fix 自动修复可检测的常见问题（如配置缺失、端口占用）
openclaw status --all 生成完整诊断报告（含组件状态、资源占用、API连通性）

6.3 日志路径

  • Windows：C:\Users\<用户名>\.openclaw\logs
  • Linux：/home/<用户名>/.openclaw/logs
  • 系统服务日志（Gateway）：
    • Windows：事件查看器 → 应用程序和服务日志 → OpenClaw
    • Linux：/var/log/openclaw/gateway.log

7. 模型管理

7.1 模型基础操作

命令 功能说明
openclaw models list 列出所有可用模型（含内置/自定义）
openclaw models status 检查模型认证状态、接口连通性
openclaw models set-default <模型名> 设置默认使用的模型

7.2 模型认证与配置

# 批量导入模型令牌
openclaw models auth import --file ./model-tokens.json

# 验证模型接口可用性
openclaw models test <模型名> --prompt "测试内容"

model-tokens.json 格式示例：

{
  "GPT-5": "sk-xxxxxx",
  "Claude": "claude-xxxxxx",
  "ERNIE": "ernie-xxxxxx"
}

8. 故障排除

8.1 常见问题及解决

问题现象 排查步骤 解决方法
启动网关提示端口占用 1. openclaw doctor 检测端口
2. `netstat -ano		 findstr :8080`（Windows）查看占用进程
渠道登录失败 1. openclaw channels status --probe 检测
2. 查看日志：openclaw logs --level ERROR		 1. 检查网络连通性
2. 验证渠道令牌/扫码授权有效性
3. 重新登录：openclaw channels login <渠道名>
模型调用无响应 1. openclaw models status 检查认证
2. 测试模型接口：openclaw models test <模型名>		 1. 重新配置模型令牌：openclaw models auth setup-token
2. 检查模型服务商接口状态
3. 切换默认模型：openclaw models set-default <备用模型>

8.2 重置操作

# 仅重置配置（保留数据/日志）
openclaw reset --config

# 完全重置（清空配置、数据、日志）
openclaw reset --full

# 重置指定渠道配置
openclaw reset --channel feishu

9. 实战示例

9.1 基础运维流程

# 1. 启动核心服务与网关
openclaw start
openclaw gateway start

# 2. 登录飞书渠道并验证状态
openclaw channels login feishu
openclaw channels status --probe

# 3. 发送测试消息验证连通性
openclaw message send --target "ou_789012" --message "OpenClaw服务已启动，可正常使用"

# 4. 实时监控日志
openclaw logs --follow

9.2 技能部署与使用

# 1. 安装自动回复技能
openclaw skills install feishu-auto-reply

# 2. 启用技能并配置回复规则
openclaw skills enable feishu-auto-reply
openclaw config set skills.feishu-auto-reply.rule="./reply-rule.json"

# 3. 触发技能执行
openclaw exec "skill run feishu-auto-reply"

9.3 故障应急处理

# 1. 检测并自动修复问题
openclaw doctor --fix

# 2. 若网关异常，重启并验证
openclaw gateway restart
openclaw gateway status

# 3. 导出错误日志用于排查
openclaw logs --level ERROR --limit 200 > ./error-logs-20240101.txt

附录

权限说明

  • 所有命令建议以管理员/root权限运行，避免权限不足导致的服务启动失败、文件读写异常
  • Linux系统可通过 sudo openclaw <命令> 执行，Windows需右键终端选择“以管理员身份运行”

帮助与支持

# windows
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Agent执行Shell命令：Docker沙箱真的能防住恶意rm -rf吗？

avatar 龙虾开发者社区
cover

Slack 消息通道实战：Socket Mode 穿透内网 vs 公网 Webhook 的 Agent 安全选型

avatar 龙虾开发者社区
cover

OpenClaw 密钥路由实战：多厂商 API 熔断与动态配额管理

avatar 龙虾开发者社区