OpenClaw 飞书安装部署 ZeroClaw 并 GitHub Issue 提交实战经验
1. **自然语言交互的强大**：通过 OpenClaw Feishu 通道，我能够用自然语言完成所有操作，无需记忆复杂的命令。- ✅ 正确的 feature 名称是 `channel-lark`（不是 `channel-feishu`）- 前端代码逻辑正确（`/root/zeroclaw/web/src/lib/ws.ts`）| 特性 | ZeroClaw (Rust) | OpenClaw (
## 📋 文档概述
本文档记录了使用 OpenClaw 的 Feishu 通道，通过自然语言交互完成以下任务的完整过程：
1. ✅ 安装部署 ZeroClaw（Rust-based AI Agent 框架）
2. ✅ 启用 Feishu/Lark channel 支持
3. ✅ 配置 OpenClaw GitHub 集成
4. ✅ 发现并分析 ZeroClaw 存在的 5 个问题
5. ✅ 向 ZeroClaw GitHub 仓库提交 5 个 Issues
**时间线**: 2026-03-08 12:00 - 22:00 (10 小时)
**交互方式**: Feishu 自然语言对话
**工具**: OpenClaw (2026.2.9) + ZeroClaw (0.1.9)
---
## 🎯 任务背景
### 初始需求
通过 OpenClaw Feishu 通道提出了以下需求：
1. 安装部署 ZeroClaw（Rust-based AI Agent 框架）
2. 启用 Feishu/Lark channel 支持
3. 配置 OpenClaw GitHub 集成
4. 发现 ZeroClaw 存在的问题
5. 提交 GitHub Issues
### 为什么选择 ZeroClaw？
ZeroClaw 是一个用 Rust 编写的高性能 AI Agent 框架，与 OpenClaw（Node.js/TypeScript）形成技术互补：
| 特性 | ZeroClaw (Rust) | OpenClaw (Node.js) |
|------|-----------------|-------------------|
| 性能 | 极致性能（20MB 内存） | 灵活性优先（~100MB 内存） |
| 语言 | Rust（编译型） | TypeScript（解释型） |
| 架构 | 单体应用 | 插件化架构 |
| 学习曲线 | 陡峭 | 平缓 |
---
## 📀 第一阶段：ZeroClaw 安装部署
### 步骤 1：安装 Rust 工具链
**自然语言指令**：
```
"请安装 ZeroClaw"
```
**执行过程**：
```bash
# 检查 Rust 版本
$ rustc --version
rustc 1.87.0
# 检查 Cargo 版本
$ cargo --version
cargo 1.87.0
✅ Rust 工具链已安装
```
### 步骤 2：克隆 ZeroClaw 源码
```bash
# 克隆仓库
$ git clone https://github.com/zeroclaw-labs/zeroclaw.git
Cloning into 'zeroclaw'...
remote: Enumerating objects: 32000, done.
remote: Total 32000 (delta 0), reused 0 (delta 0), pack-reused 32000
Receiving objects: 100% (32000/32000), 15.2 MiB | 12.5 MiB/s, done.
# 进入目录
$ cd zeroclaw
```
### 步骤 3：编译安装 ZeroClaw
**自然语言指令**：
```
"编译并安装 ZeroClaw"
```
**执行过程**：
```bash
# 初始安装（不含 Feishu 支持）
$ cargo install --path . --locked
Compiling zeroclaw v0.1.9 (/root/zeroclaw)
Finished `release` profile [optimized] target(s) in 8m 12s
Replacing package
✅ ZeroClaw 安装成功
# 验证安装
$ zeroclaw --version
zeroclaw 0.1.9
✅ ZeroClaw v0.1.9 安装完成
```
### 步骤 4：配置 ZeroClaw Gateway
**自然语言指令**：
```
"配置 ZeroClaw Gateway 支持外部访问"
```
**执行过程**：
```bash
# 创建配置目录
$ mkdir -p /root/.zeroclaw
# 生成配置
$ zeroclaw doctor
✅ Config written to /root/.zeroclaw/config.toml
# 编辑配置，监听所有网络接口
$ nano /root/.zeroclaw/config.toml
# 修改 gateway 配置
[gateway]
host = "0.0.0.0" # 允许外部访问
port = 42617
require_pairing = true
```
### 步骤 5：创建 Systemd 服务
**自然语言指令**：
```
"创建 systemd 服务让 ZeroClaw Gateway 开机自启"
```
**执行过程**：
```bash
# 创建 systemd 服务文件
$ cat > /etc/systemd/system/zeroclaw-gateway.service << 'EOF'
[Unit]
Description=ZeroClaw Gateway Service
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/root
ExecStart=/root/.cargo/bin/zeroclaw gateway
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
# 重新加载 systemd
$ systemctl daemon-reload
# 启用并启动服务
$ systemctl enable zeroclaw-gateway
$ systemctl start zeroclaw-gateway
# 验证服务状态
$ systemctl status zeroclaw-gateway
● zeroclaw-gateway.service - ZeroClaw Gateway Service
Loaded: loaded (/etc/systemd/system/zeroclaw-gateway.service; enabled)
Active: active (running) since Sun 2026-03-08 15:34:26 CST
✅ ZeroClaw Gateway 服务已启动
```
### 步骤 6：配置配对（Pairing）
```bash
# 查看 Gateway 日志，获取配对码
$ journalctl -u zeroclaw-gateway -n 20 --no-pager | grep "pairing"
Mar 08 15:34:26 zeroclaw[277961]: 🔐 Pairing: ACTIVE
Mar 08 15:34:26 zeroclaw[277961]: 📝 Pairing code: 313879
✅ 配对码：313879
✅ Dashboard URL: http://111.22.33.44:42617/
```
---
## 🔧 第二阶段：启用 Feishu Channel 支持
### 步骤 1：发现 Feature 问题
**自然语言指令**：
```
"启用 Feishu channel 支持"
```
**执行过程**：
```bash
# 尝试编译（使用错误的 feature 名称）
$ cargo install --path . --features "channel-feishu" --force
error: package `zeroclaw` does not contain these features: channel-feishu
❌ Feature 名称错误！
```
### 步骤 2：分析源码找到正确的 Feature 名称
**自然语言指令**：
```
"查看 Cargo.toml 找到正确的 Feishu feature 名称"
```
**执行过程**：
```bash
# 查看 Cargo.toml
$ cat /root/zeroclaw/Cargo.toml | grep -A 5 "features"
[features]
default = []
channel-lark = ["dep:prost"] # ← 发现正确的名称是 channel-lark
```
**关键发现**：
- ✅ 正确的 feature 名称是 `channel-lark`（不是 `channel-feishu`）
- ⚠️ 这个命名很 confusing
### 步骤 3：重新编译（含 Feishu 支持）
**自然语言指令**：
```
"重新编译 ZeroClaw，启用 channel-lark feature"
```
**执行过程**：
```bash
# 停止旧服务
$ systemctl stop zeroclaw-gateway
# 重新编译（正确的 feature 名称）
$ cargo install --path . --features "channel-lark" --force --locked
Updating crates.io index
Compiling proc-macro2 v1.0.106
Compiling unicode-ident v1.0.24
...
Finished `release` profile [optimized] target(s) in 12m 15s
Replacing package
✅ 编译成功（12分15秒）
# 安装新二进制
$ cp /root/zeroclaw/target/release/zeroclaw /root/.cargo/bin/zeroclaw
# 重启服务
$ systemctl start zeroclaw-gateway
# 验证 Feishu 支持
$ journalctl -u zeroclaw-gateway --since "2 minutes ago" --no-pager
✅ Feishu channel 已启用
```
---
## 🔍 第三阶段：问题发现与分析
### 问题 1：Dashboard WebSocket 认证失败
**自然语言指令**：
```
"打开 ZeroClaw Dashboard，看看 Agent 页面是否正常"
```
**发现过程**：
1. 访问 Dashboard：http://111.22.33.44:42617/
2. 输入配对码：313879
3. 导航到 Agent 页面
4. **发现问题**：WebSocket 连接失败
**诊断过程**：
```javascript
// 在浏览器控制台运行诊断脚本
(function() {
const token = sessionStorage.getItem('zeroclaw_token');
console.log('Token:', token ? `${token.substring(0, 20)}...` : 'NOT FOUND');
const originalWebSocket = window.WebSocket;
window.WebSocket = function(url, protocols) {
console.log('WebSocket 被创建:');
console.log(' URL:', url);
console.log(' Protocols:', protocols); // ← 关键检查点
const ws = new originalWebSocket(url, protocols);
ws.onopen = (e) => console.log('✅ onopen:', e);
ws.onerror = (e) => console.error('❌ onerror:', e);
ws.onclose = (e) => console.log('🔌 onclose: code=' + e.code);
return ws;
};
console.log('监控已启用，请点击 Agent 菜单');
})();
```
**输出结果**：
```
Token: zc_67d823cbf42028a23...
WebSocket 被创建:
URL: ws://111.22.33.44:42617/ws/chat?session_id=sess_mmh82u95_000l5bcc
Protocols: // ← 空的！这是问题所在！
❌ WebSocket connection failed
```
**根本原因**：
- 前端代码逻辑正确（`/root/zeroclaw/web/src/lib/ws.ts`）
- 但运行时 `protocols` 参数为空/undefined
- 导致 WebSocket 无法认证
**提交 Issue**：#3011
---
### 问题 2：Feishu Channel Feature 名称混淆
**自然语言指令**：
```
"分析为什么 Feishu feature 名称是 channel-lark 而不是 channel-feishu"
```
**发现过程**：
```bash
# 查看源码
$ cat /root/zeroclaw/Cargo.toml | grep -A 2 "channel-lark"
[features]
default = [] # ← 空的！没有默认启用任何 channels
channel-lark = ["dep:prost"]
```
**问题分析**：
1. **Feature 名称混淆**
- 代码支持 Feishu 和 Lark
- 但 feature 名称只有 `channel-lark`
- 没有 `channel-feishu` 别名
2. **未默认启用**
- `default = []` 为空
- 中国用户需要重新编译
3. **配置混乱**
- 配置 section 名是 `lark`
- 但标志是 `use_feishu`
**提交 Issue**：#3012
---
### 问题 3：Onboard 命令安全性问题
**自然语言指令**：
```
"查看 zeroclaw onboard 命令的帮助信息"
```
**发现过程**：
```bash
$ zeroclaw onboard --help
Options:
--force
Overwrite existing config without confirmation
⚠️ 危险！--force 会覆盖所有配置！
```
**问题分析**：
1. **缺少 `--reinit` 标志**
- 无法明确区分"配置"和"重新初始化"
- 容易意外覆盖现有配置
2. **建议的行为**：
- `zeroclaw onboard` → 安全模式（只配置未设置的）
- `zeroclaw onboard --reinit` → 清除配置，需要确认
- `zeroclaw onboard --force` → 已弃用，显示警告
**提交 Issue**：#3013
---
### 问题 4：Gateway Restart 命令缺失
**自然语言指令**：
```
"查看 zeroclaw gateway 命令有哪些子命令"
```
**发现过程**：
```bash
$ zeroclaw gateway --help
Options:
-p, --port <PORT>
-p, --host <HOST>
--new-pairing
--open-dashboard
❌ 没有 restart、stop、status 等子命令！
```
**当前工作方式**：
```bash
# 必须使用外部工具
$ systemctl restart zeroclaw-gateway
# 或手动 kill
$ kill $(pgrep -f "zeroclaw gateway")
$ zeroclaw gateway
```
**建议的命令**：
```bash
zeroclaw gateway start # 启动
zeroclaw gateway stop # 停止
zeroclaw gateway restart # 重启
zeroclaw gateway status # 状态
zeroclaw gateway logs # 日志
```
**提交 Issue**：#3014
---
### 问题 5：Get Paircode 命令缺失
**自然语言指令**：
```
"如何查看当前的配对码？"
```
**发现过程**：
```bash
# 查看日志（不方便）
$ journalctl -u zeroclaw-gateway | grep "pairing code"
# 或重启 Gateway（破坏性！）
$ zeroclaw gateway --new-pairing # ← 这会清除所有配对！
```
**问题分析**：
1. **`--new-pairing` 的问题**：
- 清除所有配对的 tokens
- 需要重启 Gateway
- 所有客户端需要重新配对
2. **建议的命令**：
```bash
# 显示当前配对码
$ zeroclaw gateway get-paircode
✅ Current pairing code: 313879
# 生成新配对码（不重启）
$ zeroclaw gateway get-paircode --new
✅ New pairing code: 728461
✅ Existing devices: 3 (still active)
# 显示 QR 码
$ zeroclaw gateway get-paircode --qr
```
**提交 Issue**：#3015
---
## 📝 第四阶段：GitHub Issues 提交
### 准备 GitHub Token
**自然语言指令**：
```
"配置 GitHub Token 用于提交 Issues"
```
**提供的 Token**：
```
github_token
```
**配置过程**：
```bash
# 使用 GitHub API 提交 Issue
export GITHUB_TOKEN="github_token"
```
### 提交 Issue #3011：Dashboard WebSocket
**自然语言指令**：
```
"提交第一个 Issue：Dashboard WebSocket 认证失败"
```
**执行过程**：
```python
import requests
issue_body = open('/tmp/zeroclaw-bug-report.md').read()
payload = {
"title": "Dashboard WebSocket protocols parameter not passed, causing authentication failure",
"body": issue_body
}
response = requests.post(
"https://api.github.com/repos/zeroclaw-labs/zeroclaw/issues",
json=payload,
headers={
"Authorization": "Bearer github_token",
"Accept": "application/vnd.github.v3+json",
"Content-Type": "application/json"
}
)
print(f"✅ Issue 创建成功！")
print(f"Issue URL: {response.json()['html_url']}")
```
**结果**：
- ✅ Issue #3011 提交成功
- URL: https://github.com/zeroclaw-labs/zeroclaw/issues/3011
- 优先级: Critical
### 提交 Issue #3012：Feishu Channel 配置
**自然语言指令**：
```
"提交第二个 Issue：Feishu Channel 配置混乱"
```
**结果**：
- ✅ Issue #3012 提交成功
- URL: https://github.com/zeroclaw-labs/zeroclaw/issues/3012
- 优先级: Medium
### 提交 Issue #3013：Onboard 安全性
**自然语言指令**：
```
"提交第三个 Issue：Onboard 命令安全性问题"
```
**结果**：
- ✅ Issue #3013 提交成功
- URL: https://github.com/zeroclaw-labs/zeroclaw/issues/3013
- 优先级: Critical
### 提交 Issue #3014：Gateway Restart
**自然语言指令**：
```
"提交第四个 Issue：Gateway Restart 命令缺失"
```
**结果**：
- ✅ Issue #3014 提交成功
- URL: https://github.com/zeroclaw-labs/zeroclaw/issues/3014
- 优先级: Medium
### 提交 Issue #3015：Get Paircode
**自然语言指令**：
```
"提交第五个 Issue：Get Paircode 命令缺失"
```
**结果**：
- ✅ Issue #3015 提交成功
- URL: https://github.com/zeroclaw-labs/zeroclaw/issues/3015
- 优先级: Medium
---
## 📊 第五阶段：总结与统计
### 完成统计
| 阶段 | 任务 | 状态 | 耗时 |
|------|------|------|------|
| 安装部署 | ZeroClaw 安装 | ✅ | 10分钟 |
| 安装部署 | Gateway 配置 | ✅ | 5分钟 |
| 安装部署 | Systemd 服务 | ✅ | 5分钟 |
| Feishu 支持 | 重新编译（含 Feishu） | ✅ | 12分15秒 |
| 问题发现 | 发现 5 个问题 | ✅ | 2小时 |
| Issues 提交 | 提交 5 个 GitHub Issues | ✅ | 30分钟 |
**总耗时**: 约 3 小时（实际交互时间 10 小时）
### 提交的 Issues
| Issue | 编号 | 标题 | 优先级 |
|-------|------|------|--------|
| Dashboard WebSocket | #3011 | WebSocket protocols parameter not passed | Critical |
| Feishu Channel | #3012 | channel-lark feature misnamed | Medium |
| Onboard Safety | #3013 | onboard command can overwrite config | Critical |
| Gateway Restart | #3014 | Add gateway restart command | Medium |
| Get Paircode | #3015 | Add get-paircode command | Medium |
**统计**：
- Critical: 2个 (40%)
- Medium: 3个 (60%)
- Bug: 2个 (40%)
- Feature Request: 2个 (40%)
- Enhancement: 1个 (20%)
### 技能提升
通过这次实践，掌握的技能：
1. ✅ **Rust 生态**
- Cargo 构建系统
- Feature flags
- 重新编译流程
2. ✅ **系统管理**
- Systemd 服务管理
- 进程监控
- 日志分析
3. ✅ **网络诊断**
- WebSocket 调试
- 浏览器开发者工具
- 网络抓包
4. ✅ **问题分析**
- 源码阅读
- 根因分析
- 解决方案设计
5. ✅ **开源贡献**
- GitHub Issues 提交
- Bug 报告撰写
- 技术文档编写
---
## 💡 关键经验总结
### 1. 自然语言交互的优势
**优势**：
- ✅ **无需记忆命令**：用自然语言描述需求即可
- ✅ **上下文理解**：AI 能理解复杂的需求
- ✅ **自动化执行**：AI 自动选择合适的工具和命令
- ✅ **持续对话**：可以逐步细化需求
**示例对比**：
**传统方式**：
```bash
# 需要记忆命令
$ systemctl restart zeroclaw-gateway
$ journalctl -u zeroclaw-gateway -n 50
$ cargo install --path . --features "channel-lark" --force
```
**自然语言方式**：
```
"重启 ZeroClaw Gateway"
"查看最近的 Gateway 日志"
"重新编译 ZeroClaw，启用 Feishu 支持"
```
### 2. 问题发现的技巧
**技巧 1：从症状到根因**
```
症状：Dashboard Agent 页面无法连接
↓
诊断：浏览器控制台查看 WebSocket
↓
发现：protocols 参数为空
↓
根因：前端代码逻辑正确但运行时失败
```
**技巧 2：对比分析**
```
对比：ZeroClaw vs OpenClaw
↓
发现：ZeroClaw 的 feature 名称混淆
↓
原因：channel-lark vs channel-feishu
↓
建议：添加别名，改善文档
```
**技巧 3：实际使用测试**
```
实际使用：zeroclaw gateway --new-pairing
↓
发现：会清除所有配对（破坏性）
↓
问题：没有安全的查看配对码方式
↓
建议：添加 get-paircode 命令
```
### 3. Issue 撰写的最佳实践
**结构**：
1. **Summary**：简短描述问题
2. **Environment**：环境信息
3. **Steps to Reproduce**：重现步骤
4. **Expected Behavior**：期望行为
5. **Actual Behavior**：实际行为
6. **Root Cause**：根本原因
7. **Suggested Fix**：建议修复
**示例**：
```markdown
# Bug Report: Dashboard WebSocket 认证失败
## Summary
WebSocket 连接失败，protocols 参数未传递
## Environment
- ZeroClaw Version: 0.1.9
- OS: OpenCloudOS
## Steps to Reproduce
1. 启动 Gateway
2. 打开 Dashboard
3. 导航到 Agent 页面
4. 观察 WebSocket 连接
## Expected Behavior
WebSocket 应该创建时包含 protocols 参数
## Actual Behavior
protocols 参数为空/undefined
## Root Cause
前端代码逻辑正确但运行时失败
## Suggested Fix
添加防御性日志，验证 protocols 参数
```
### 4. 编译型语言的挑战
**挑战 1：编译时间**
- ZeroClaw 编译耗时：8-12 分钟
- 解决：使用 `--force` 跳过依赖检查
**挑战 2：Feature 名称**
- 错误：`channel-feishu`
- 正确：`channel-lark`
- 解决：查看 `Cargo.toml` 确认
**挑战 3：调试困难**
- Rust 编译型语言，调试困难
- 解决：使用日志和监控
### 5. 系统集成的复杂性
**挑战 1：服务管理**
- 需要创建 systemd 服务
- 配置自动启动
- 监控服务状态
**挑战 2：网络配置**
- 配置 Gateway 监听所有接口
- 配置防火墙规则
- 配置反向代理（可选）
**挑战 3：日志管理**
- 日志分散在多个地方
- systemd journal
- 应用日志
---
## 🎯 未来改进建议
### 对 ZeroClaw 项目
**高优先级**：
1. ✅ 修复 Dashboard WebSocket 问题（#3011）
2. ✅ 添加 Onboard `--reinit` 标志（#3013）
**中优先级**：
3. ✅ 改进 Feishu feature 名称（#3012）
4. ✅ 添加 Gateway restart 命令（#3014）
5. ✅ 添加 get-paircode 命令（#3015）
### 对 OpenClaw 项目
**保持优势**：
1. ✅ 优秀的 Feishu 集成（文档、Wiki、云盘）
2. ✅ 丰富的插件生态
3. ✅ 详细的文档
4. ✅ 自然语言交互
---
## 📚 相关资源
### 文档
- **ZeroClaw**: https://github.com/zeroclaw-labs/zeroclaw
- **OpenClaw**: https://docs.openclaw.ai
- **Rust**: https://www.rust-lang.org/zh-CN/
### 工具
- **Cargo**: Rust 包管理器
- **Systemd**: Linux 服务管理器
- **GitHub API**: 用于自动提交 Issues
### 代码仓库
- **ZeroClaw**: https://github.com/zeroclaw-labs/zeroclaw
- **提交的 Issues**:
- #3011: https://github.com/zeroclaw-labs/zeroclaw/issues/3011
- #3012: https://github.com/zeroclaw-labs/zeroclaw/issues/3012
- #3013: https://github.com/zeroclaw-labs/zeroclaw/issues/3013
- #3014: https://github.com/zeroclaw-labs/zeroclaw/issues/3014
- #3015: https://github.com/zeroclaw-labs/zeroclaw/issues/3015
---
## 🎓 结语
通过这次完整的实践过程，我深刻体会到了：
1. **自然语言交互的强大**：通过 OpenClaw Feishu 通道，我能够用自然语言完成所有操作，无需记忆复杂的命令。
2. **问题发现的重要性**：通过实际使用发现的问题，往往比文档中描述的更有价值。
3. **开源贡献的意义**：提交 Issues 不仅是报告问题，更是帮助项目改进。
4. **持续学习的价值**：从零开始学习 Rust 和 ZeroClaw，虽然过程曲折，但收获巨大。
这次经历让我对 AI Agent 框架有了更深入的理解，也让我更加期待这两个项目的未来发展！
---
_文档编写时间：2026-03-08 22:45_
_作者：通过 OpenClaw Feishu 通道完成_
_总耗时：10 小时_
_提交 Issues：5 个_
小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用
更多推荐
4
0- 0
已为社区贡献2条内容
所有评论(0)