夜雨聆风🎯 学习目标：第三周复盘及常见问题处理
⏱️ 阅读时间：约 12 分钟
💡 前置要求：无
📚 第三周回顾
✅ 已完成内容
❓ 常见问题 Q&A
Q1: 飞书 API 调用失败？
排查步骤：
# 1. 检查应用权限# 飞书开发者后台 → 权限管理# 确认已申请对应权限# 2. 检查凭证配置openclaw config get channels.feishu.app_idopenclaw config get channels.feishu.app_secret# 3. 检查网关日志openclaw gateway logs | grep feishu# 4. 测试连通性openclaw ask "你好"Q2: 定时任务不执行？
常见原因及解决方案：
详细排查
// 1. 验证 Cron 表达式functionvalidateCron(expression) {const parts = expression.split(' ');if (parts.length !== 5) {thrownewError('无效的 Cron 表达式'); }// 验证每个部分// ...}// 2. 检查网关状态openclaw gateway status// 3. 查看任务日志openclaw gateway logs | grep cronQ3: 知识库检索不准确？
优化方法：
方法 1：调整检索参数
const results = awaitvectorSearch({embedding: questionEmbedding.vector, kbId,topK: 10, // 增加结果数量minScore: 0.3// 降低阈值});方法 2：优化文档切片
// 使用语义切片const chunks = awaitsemanticChunking(document.content);// 为每个切片生成摘要for (const chunk of chunks) { chunk.summary = awaitgenerateSummary(chunk.content); chunk.keywords = awaitextractKeywords(chunk.content);}方法 3：更新知识库
# 手动触发同步openclaw knowledge sync# 查看同步状态openclaw knowledge statusQ4: Webhook 收不到通知？
排查步骤：
# 1. 检查 Webhook 端点是否可访问curl -X POST https://your-domain.com/webhook/github# 2. 检查签名验证# 确认使用正确的 Secret# 3. 查看 Webhook 日志openclaw gateway logs | grep webhook# 4. 测试 Webhook# 在 GitHub 后台发送测试通知Q5: API 集成认证失败？
解决方案：
方法 1：检查 API Key
const secrets = newSecretManager();const apiKey = await secrets.get('API_KEY');// 验证 API Key 格式if (!apiKey || apiKey.length < 10) {thrownewError('无效的 API Key');}方法 2：自动刷新 Token
module.exports = {name: 'token-refresh',asyncinit() {// 每天检查 Token 是否过期awaitcreateCronJob({cron: '0 0 * * *',task: async () => {const tokens = awaitlistTokens();for (const token of tokens) {if (isExpiringSoon(token)) {const newToken = awaitrefreshToken(token);awaitupdateToken(token.service, newToken); } } } }); }};🎯 最佳实践总结
1. 飞书集成
✅ 推荐做法：
// 使用官方 API 格式const event = awaitfeishu_calendar_event('create', { summary,start_time: {timestamp: newDate(startTime).toISOString(),timezone: 'Asia/Shanghai' },attendee_ability: 'can_see_others'});// 错误处理try {awaitfeishu_api_call();} catch (error) {if (error.code === '99991001') {return'❌ 权限不足'; }throw error;}2. 工作流自动化
✅ 推荐做法：
// 使用 Cron 表达式awaitcreateCronJob({cron: '0 9 * * *', // 每天早上 9 点task: async () => {awaitsendDailyReport(); }});// 错误处理try {awaittask();} catch (error) {awaitnotifyAdmin('任务执行失败', error);// 重试机制awaitretry(task, 3);}3. 知识库构建
✅ 推荐做法：
// 文档切片const chunks = awaitsemanticChunking(document.content);// 向量化const embeddings = awaitcreateEmbedding({model: 'text-embedding-3-small',input: chunk.content});// RAG 检索const results = awaitvectorSearch({embedding: questionEmbedding.vector, kbId,topK: 5});4. API 集成
✅ 推荐做法：
// 使用 SecretManager 管理密钥const secrets = newSecretManager();const apiKey = await secrets.get('API_KEY');// 自动刷新 TokenawaitcreateCronJob({cron: '0 0 * * *',task: async () => {awaitrefreshToken(); }});// 错误处理try {const response = awaitfetch(url, {headers: {'Authorization': `Bearer ${apiKey}` } });if (!response.ok) {thrownewError(`HTTP ${response.status}`); }} catch (error) {console.error('API 调用失败:', error);throw error;}📊 企业级应用检查清单
部署企业级应用前，对照检查：
飞书权限配置完整 定时任务配置正确 Webhook 端点可访问 知识库已建立索引 API 密钥安全存储 错误处理完善 日志记录完整 监控告警已配置
📋 学习成果自测
完成以下任务，检验学习效果：
自测清单
能配置飞书日历和任务 能操作多维表格和云文档 能配置定时任务 能配置消息路由 能构建知识库 能调用外部 API 能配置 Webhook 能处理常见问题
评分标准
| 8 项 | ||
| 5-7 项 | ||
| < 5 项 |
🚀 第四周预告
主题：高级主题
💬 互动环节
本周收获
留言分享你最大的收获！
遇到问题
遇到什么技术难题？大家一起解决！
实战经验
你在企业级应用中遇到过什么挑战？如何解决的？
建议反馈
内容难度如何？需要调整什么？
🎉 恭喜完成第三周学习！
休息一下，明天开始高级主题之旅！🚀
公众号：OpenClaw 研习社系列：OpenClaw 30 天入门到精通作者：OpenClaw 研习社
