OpenClaw网关自愈方案

# OpenClaw Gateway 自愈方案：基于 OpenCode 的自动修复实现

> 企业级 OpenClaw Gateway 自愈能力实践，实现系统故障的自动化恢复

## 一、方案背景与价值

### 1.1 问题场景
在生产环境中，OpenClaw Gateway 可能因配置错误、插件冲突或系统资源问题而出现异常。传统的人工干预方式响应延迟长、运维效率低，影响系统可用性。

### 1.2 方案价值
本方案通过集成 OpenCode AI 助手与 systemd 自愈机制，实现 Gateway 故障的自动化检测与修复，显著提升系统可靠性。

---

## 二、技术架构与实现

### 2.1 系统架构概述

```mermaid
flowchart TD
    A[Gateway 异常崩溃] --> B[systemd OnFailure 触发]
    B --> C[启动 OpenCode<br/>修复脚本]
    C --> D{OpenCode<br/>分析错误}
    D -->|分析成功| E[生成修复方案]
    D -->|分析失败| F[记录分析失败]
    E --> G[应用修复配置]
    G --> H{配置验证<br/>通过?}
    H -->|是| I[重启 Gateway 服务]
    H -->|否| J[记录修复失败]
    I --> K[修复成功通知]
    J --> K
    F --> K
    K --> L[流程结束]

    %% 样式优化：使用直线连接，紧凑布局
    linkStyle default stroke:#333,stroke-width:2px
```

### 2.2 文件结构

```
~/
├── .config/systemd/user/
│   ├── openclaw-gateway.service
│   ├── openclaw-gateway.service.d/
│   │   └── auto-fix.conf          # OnFailure 触发配置
│   └── openclaw-fix.service       # 自动修复服务
├── .openclaw/
│   ├── openclaw.json              # 主配置文件
│   └── workspace/
└── scripts/
    └── opencode-fix.sh            # 核心修复脚本
```

### 2.2 核心组件

#### 2.2.1 OpenCode 自动修复脚本 (`opencode-fix.sh`)

核心修复脚本负责故障分析、修复方案生成和服务恢复：

```bash
#!/usr/bin/env bash
# opencode-fix.sh — OpenCode 自动修复脚本
set -euo pipefail

SERVICE_NAME="${OPENCLAW_GATEWAY_UNIT:-openclaw-gateway.service}"
GATEWAY_PORT="${OPENCLAW_GATEWAY_PORT:-18789}"

# 通知配置
NOTIFY_TARGET="${OPENCLAW_FIX_TELEGRAM_TARGET:-feishu-default}"

# 路径配置
OPENCLAW_CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"
LOG_DIR="${OPENCLAW_LOG_DIR:-/tmp/openclaw}"
LOG_DATE="$(date -u +%Y-%m-%d)"
LOG_FILE="${LOG_DIR}/openclaw-${LOG_DATE}.log"

MAX_RETRIES="${OPENCLAW_FIX_MAX_RETRIES:-2}"
OPENCODE_TIMEOUT_SECS="${OPENCLAW_FIX_OPENCODE_TIMEOUT_SECS:-300}"

# 单实例锁定机制
LOCK_FILE="${XDG_RUNTIME_DIR:-/tmp}/opencode-fix.lock"
exec 9>"$LOCK_FILE"
flock -n 9 || { echo "另一个 opencode-fix 正在运行，退出"; exit 0; }

# 通知函数
notify() {
    local msg="$1"
    [[ -z "$NOTIFY_TARGET" ]] && return 0
    openclaw message send --channel feishu --target "$NOTIFY_TARGET" --message "$msg" 2>/dev/null || true
}

# 查找 OpenCode 可执行文件
find_opencode() {
    local c
    c="$(command -v opencode 2>/dev/null || true)"
    if [[ -n "$c" && -x "$c" ]]; then echo "$c"; return 0; fi
    for candidate in "$HOME/.local/bin/opencode" "/usr/local/bin/opencode" "$HOME/.nvm/versions/node/v24.14.0/bin/opencode"; do
        if [[ -x "$candidate" ]]; then echo "$candidate"; return 0; fi
    done
    echo ""
}

# 收集错误上下文信息
collect_errors() {
    echo "=== 日志尾部错误 ==="
    if [[ -f "$LOG_FILE" ]]; then
        tail -80 "$LOG_FILE" 2>/dev/null | grep -i "error\\|fatal\\|invalid\\|failed\\|EADDRINUSE" | tail -20 || true
    fi
    echo ""
    echo "=== journalctl ($SERVICE_NAME) ==="
    journalctl --user -u "$SERVICE_NAME" --no-pager -n 40 2>/dev/null || true
}

# 验证配置 JSON 格式
validate_config_json() {
    if [[ -f "$OPENCLAW_CONFIG_PATH" ]]; then
        python3 -m json.tool "$OPENCLAW_CONFIG_PATH" >/dev/null 2>&1
    fi
}

# 重启服务并检查状态
restart_and_check() {
    systemctl --user reset-failed "$SERVICE_NAME" 2>/dev/null || true
    systemctl --user restart "$SERVICE_NAME" 2>/dev/null || true
    sleep 8
    systemctl --user is-active "$SERVICE_NAME" >/dev/null 2>&1
}

# ---- 主程序逻辑 ----
ERROR_CONTEXT="$(collect_errors)"

# 配置完整性检查
if [[ -f "$OPENCLAW_CONFIG_PATH" ]] && ! validate_config_json; then
    notify "🔴 Gateway 配置 JSON 无效: $OPENCLAW_CONFIG_PATH"
    exit 1
fi

# OpenCode 可用性检查
OPENCODE_CMD="$(find_opencode)"
if [[ -z "$OPENCODE_CMD" ]]; then
    notify "🔴 $SERVICE_NAME 失败。未找到 OpenCode；无法自动修复。"
    exit 1
fi

notify "🔧 $SERVICE_NAME 失败。启动 OpenCode 自动修复流程…"

for attempt in $(seq 1 "$MAX_RETRIES"); do
    FIX_PROMPT="OpenClaw Gateway 重复失败。分析问题并提供修复方案。

服务: $SERVICE_NAME
网关端口: $GATEWAY_PORT

错误上下文:
$ERROR_CONTEXT

修复原则:
- 优先最小化更改
- 除非明确损坏，否则保留有效配置
- 修复后验证 JSON 格式
- 确保服务可正常重启

请提供详细的修复操作说明。"

    # 调用 OpenCode 进行故障分析
    echo "[opencode-fix] 开始 OpenCode 分析 (尝试 $attempt)..."
    
    fix_output=$(timeout "$OPENCODE_TIMEOUT_SECS" "$OPENCODE_CMD" run --dir "$HOME" "$FIX_PROMPT" 2>&1 || echo "OpenCode 分析失败或超时")

    echo "[opencode-fix] 尝试 $attempt 输出摘要:"
    echo "$fix_output" | tail -40

    # 修复后配置验证
    if [[ -f "$OPENCLAW_CONFIG_PATH" ]] && ! validate_config_json; then
        notify "🔴 自动修复尝试 $attempt 产生了无效 JSON。不重启服务。"
        continue
    fi

    if restart_and_check; then
        notify "✅ Gateway 自动修复并成功重启 (尝试 $attempt)。"
        exit 0
    fi

    ERROR_CONTEXT="$(collect_errors)"
done

notify "🔴 Gateway 自动修复在 $MAX_RETRIES 次尝试后失败。需要人工干预。"
exit 1
```

#### 2.2.2 systemd 服务集成

自动修复服务配置 (`/root/.config/systemd/user/openclaw-fix.service`):

```ini
[Unit]
Description=OpenClaw Gateway Auto-Fix (triggered on failure)

[Service]
Type=oneshot
ExecStart=/root/scripts/opencode-fix.sh
Environment=HOME=/root
Environment="PATH=/root/.nvm/current/bin:/root/.local/bin:/usr/local/bin:/usr/bin:/bin"
# 飞书通知配置
Environment=OPENCLAW_FIX_TELEGRAM_TARGET=feishu-default
TimeoutStartSec=750
```

#### 2.2.3 Gateway 服务故障触发配置

OnFailure 触发机制 (`/root/.config/systemd/user/openclaw-gateway.service.d/auto-fix.conf`):

```ini
[Unit]
# 服务失败时触发自动修复
OnFailure=openclaw-fix.service
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Restart=always
```

---

## 三、部署与配置

### 3.1 OpenCode 安装与配置

#### 3.1.1 安装方法

**方案一：npm 安装**
```bash
npm install -g opencode-ai
```

**方案二：脚本安装**
```bash
curl -fsSL https://opencode.ai/install.sh | sh
```

#### 3.1.2 配置要点

1. **权限配置**：OpenCode 需要访问 OpenClaw 配置目录的权限
```bash
export OPENCLAW_ALLOW_EXTERNAL_DIRECTORIES="/root/.openclaw/*:/root/.openclaw/workspace/*"
```

2. **调用方式**：OpenCode 的命令行参数与 Claude Code 不同，需正确配置
```bash
# 正确调用方式
opencode run --dir "$HOME" "修复提示文本"
```

3. **超时设置**：合理配置超时防止分析过程无限等待

#### 3.1.3 Skill 集成

为增强 OpenCode 的 OpenClaw 专业知识，集成 OpenClaw-Skill 参考文档：

```bash
# 克隆技能库到 OpenCode 技能目录
git clone https://github.com/win4r/OpenClaw-Skill.git ~/.opencode/skills/OpenClaw-Skill
```

OpenClaw-Skill 提供了 OpenClaw Gateway 的完整配置参考和错误模式识别能力。

### 3.2 系统集成验证

部署完成后需验证以下关键点：

1. **OpenCode 可用性**：`opencode --version`
2. **脚本权限**：`chmod +x /root/scripts/opencode-fix.sh`
3. **服务配置**：`systemctl --user cat openclaw-fix.service`
4. **触发机制**：验证 OnFailure 配置正确性

---

## 四、验证

### 4.1 触发条件测试

自动修复系统在以下条件下激活：
- Gateway 在 60 秒内崩溃 5 次
- 配置错误导致服务无法启动
- 系统资源异常触发服务故障

### 4.2 测试流程

```bash
# 1. 制造可控的配置错误
systemctl --user stop openclaw-gateway.service
echo '{"invalid": syntax_error' > /root/.openclaw/openclaw.json

# 2. 触发自动修复机制
systemctl --user start openclaw-gateway.service

# 3. 监控修复过程
journalctl --user -u openclaw-fix.service -f
```

### 4.3 预期结果

- OpenCode 自动分析错误日志并生成修复方案
- 修复后配置通过 JSON 格式验证
- Gateway 服务成功重启
- 修复状态通过飞书渠道通知

---

## 五、关键发现与最佳实践

### 5.1 技术发现

1. **systemd 触发机制**：OnFailure 需要真正的服务崩溃事件，正常停止不会触发
2. **权限配置**：OpenCode 需要明确的目录访问权限配置
3. **调用适配**：不同 AI 助手的命令行接口存在差异，需针对性适配

### 5.2 生产环境建议

#### 5.2.1 安全考虑
- 限制 OpenCode 的文件系统访问范围
- 实施最小权限原则
- 建立修复操作审计机制

#### 5.2.2 监控与告警
- 记录所有自动修复操作日志
- 设置修复成功率监控指标
- 配置人工干预阈值

#### 5.2.3 回滚机制
- 维护配置备份和恢复流程
- 设置手动干预开关
- 保持运维人员监督机制

---

## 六、方案总结

✅ **OpenCode 有效支持** OpenClaw Gateway 的自动化修复功能  
✅ **systemd OnFailure 机制** 与 AI 修复系统实现无缝集成  
✅ **开源 AI 方案** 在企业级系统运维场景中具备实用价值  
✅ **自愈能力建设** 显著提升系统可靠性和运维效率  

本方案为 OpenClaw Gateway 提供了生产就绪的自愈解决方案，在保障系统稳定性的同时，有效降低了运维复杂度。

---

## 相关链接

- [OpenClaw-Skill](https://github.com/win4r/OpenClaw-Skill) - OpenClaw 配置参考文档
- [OpenClaw 官方文档](https://docs.openclaw.ai)
- [OpenCode 项目](https://github.com/opencode-ai/opencode)

---

[返回目录](../openclaw-enterprise-hands-on-guide.md)

*文档版本：v1.0*  
*最后更新：2026-03-26*  
*验证环境：OpenClaw Gateway + OpenCode 1.3.2*