AgentScope 集成方案 - 复杂任务执行系统设计

复杂任务执行系统调研与设计方案

---
title: blog.lazyyoun.xyz HTTPS 证书申请完整指南
date: 2026-03-23
tags: [HTTPS, SSL, Certbot, Nginx]
category: 运维手册
---

# blog.lazyyoun.xyz HTTPS 证书申请完整指南

> 📋 **本文记录**：使用 Certbot 为 `blog.lazyyoun.xyz` 申请 Let's Encrypt 免费 HTTPS 证书的完整流程和注意事项。

---

## 🎯 一、环境信息

| 项目 | 值 |
|------|-----|
| **服务器** | xx.xx.xx.xx (阿里云) |
| **系统** | Alibaba Cloud Linux 3 |
| **域名** | `blog.lazyyoun.xyz` |
| **Web 服务器** | Nginx 1.20.1 |
| **证书类型** | Let's Encrypt (90 天有效期) |
| **验证方式** | DNS TXT 记录验证 |

---

## 🔧 二、安装 Certbot

### 2.1 安装命令

```bash
# 阿里云 Linux 3 / CentOS
yum install -y epel-release
yum install -y certbot python3-certbot-nginx
```

### 2.2 验证安装

```bash
certbot --version
# 输出：certbot 2.x.x
```

---

## 📝 三、申请证书流程

### 3.1 执行申请命令

```bash
certbot certonly -d blog.lazyyoun.xyz --manual --preferred-challenges dns --agree-tos --email admin@lazyyoun.xyz
```

**参数说明**：
- `certonly` - 只申请证书，不自动配置
- `-d` - 指定域名
- `--manual` - 手动模式（需要手动配置 DNS）
- `--preferred-challenges dns` - 使用 DNS 验证
- `--agree-tos` - 同意服务条款
- `--email` - 接收续期通知的邮箱

### 3.2 获取 TXT 记录值

执行命令后会输出：

```
Please deploy a DNS TXT record under the name:

_acme-challenge.blog.lazyyoun.xyz.

with the following value:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Before continuing, verify the TXT record has been deployed.
```

**记下这个 TXT 记录值**，下一步要用。

### 3.3 配置 DNS TXT 记录

#### 登录阿里云 DNS 控制台

1. 访问 https://dns.console.aliyun.com/
2. 找到 `lazyyoun.xyz` 域名
3. 点击"添加记录"

#### 添加 TXT 记录

| 字段 | 值 |
|------|-----|
| **主机记录** | `_acme-challenge.blog` |
| **记录类型** | `TXT` |
| **记录值** | (certbot 输出的值) |
| **TTL** | `10 分钟`（默认） |

**⚠️ 重要提示**：
- 如果有旧的 `_acme-challenge.blog` 记录，**请先删除**
- 只保留最新的 TXT 记录值
- 每次 certbot 重新启动都会生成新值

### 3.4 等待 DNS 生效

DNS 传播需要时间，通常 **1-5 分钟**。

#### 验证 DNS 是否生效

**方法 1：Google Admin Toolbox**
```
https://toolbox.googleapps.com/apps/dig/#TXT/_acme-challenge.blog.lazyyoun.xyz
```

**方法 2：命令行**
```bash
dig +short TXT _acme-challenge.blog.lazyyoun.xyz @8.8.8.8
```

**方法 3：nslookup**
```bash
nslookup -qt=TXT _acme-challenge.blog.lazyyoun.xyz 8.8.8.8
```

**看到正确的 TXT 记录值后**，继续下一步。

### 3.5 按回车继续验证

在 certbot 终端中**按回车键**，继续验证流程。

**成功输出**：
```
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/blog.lazyyoun.xyz/fullchain.pem
Key is saved at: /etc/letsencrypt/live/blog.lazyyoun.xyz/privkey.pem
This certificate expires on 2026-06-20.
```

---

## 🔐 四、配置 Nginx 使用证书

### 4.1 创建 Nginx 配置文件

```bash
cat > /etc/nginx/conf.d/blog.conf << 'NGINX_CONF'
server {
    listen 443 ssl;
    server_name blog.lazyyoun.xyz;

    # 证书路径
    ssl_certificate /etc/letsencrypt/live/blog.lazyyoun.xyz/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/blog.lazyyoun.xyz/privkey.pem;

    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    client_max_body_size 10M;
    
    # 网站配置
    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
    }
}

server {
    listen 80;
    server_name blog.lazyyoun.xyz;
    return 301 https://$host$request_uri;
}
NGINX_CONF
```

### 4.2 测试并重载

```bash
# 测试配置
nginx -t

# 重载 Nginx
nginx -s reload
```

### 4.3 验证 HTTPS

```bash
# 测试访问
curl -I https://blog.lazyyoun.xyz

# 应该返回 HTTP/1.1 200 OK
```

---

## ⚠️ 五、常见问题与解决方案

### 5.1 问题：Incorrect TXT record

**错误信息**：
```
Detail: Incorrect TXT record "XXX" found at _acme-challenge.blog.lazyyoun.xyz
```

**原因**：
- DNS 记录值不匹配
- 有多个 TXT 记录
- DNS 还未完全生效

**解决方案**：
1. 删除所有旧的 `_acme-challenge.blog` TXT 记录
2. 添加最新的 TXT 记录值
3. 等待 3-5 分钟再验证
4. 如果多次失败，**重新启动 certbot** 获取新值

### 5.2 问题：证书每次都生成新值

**原因**：
每次重新启动 certbot 都会生成新的 TXT 记录值。

**正确做法**：
1. 执行 certbot 命令
2. 记下 TXT 记录值
3. 配置 DNS
4. 等待 DNS 生效
5. **在同一个 certbot 进程中按回车**（不要重新启动）

**如果 certbot 已退出**：
```bash
# 重新启动 certbot，会生成新值
certbot certonly -d blog.lazyyoun.xyz --manual --preferred-challenges dns
# 使用新的 TXT 记录值
```

### 5.3 问题：DNS 一直不生效

**可能原因**：
- TTL 时间未到
- DNS 缓存
- 记录配置错误

**解决方案**：
1. 检查主机记录是否正确（`_acme-challenge.blog`）
2. 检查记录类型是否为 TXT
3. 检查记录值是否完整复制（包括所有字符）
4. 等待更长时间（最多 30 分钟）
5. 尝试使用 `@8.8.8.8` 查询，避免本地 DNS 缓存

---

## 🔄 六、证书续期

### 6.1 证书有效期

Let's Encrypt 证书有效期：**90 天**

### 6.2 手动续期

```bash
# 续期命令（与申请相同）
certbot certonly -d blog.lazyyoun.xyz --manual --preferred-challenges dns

# 续期后重载 Nginx
nginx -s reload
```

### 6.3 设置续期提醒

**建议**：
- 在证书到期前 **30 天** 设置提醒
- 可以使用日历提醒或 cron 任务

**查看证书到期时间**：
```bash
openssl x509 -in /etc/letsencrypt/live/blog.lazyyoun.xyz/fullchain.pem -noout -dates
```

### 6.4 自动续期（可选）

使用阿里云 DNS API 实现自动续期：

```bash
# 安装插件
pip3 install certbot-dns-aliyun

# 配置 API Key
cat > /root/.aliyun-credentials.ini << EOF
[default]
access_key_id = YOUR_ACCESS_KEY_ID
access_key_secret = YOUR_ACCESS_KEY_SECRET
EOF

# 自动续期
certbot certonly -d blog.lazyyoun.xyz \
  --dns-aliyun \
  --dns-aliyun-credentials /root/.aliyun-credentials.ini

# 配置定时任务（每天凌晨 2 点检查）
crontab -e
# 添加：0 2 * * * certbot renew --deploy-hook "nginx -s reload"
```

---

## 📊 七、验证工具

### 7.1 DNS 验证

- **Google Admin Toolbox**: https://toolbox.googleapps.com/apps/dig/
- **DNSViz**: https://dnsviz.net/
- **IntoDNS**: https://intodns.com/

### 7.2 SSL 验证

- **SSL Labs**: https://www.ssllabs.com/ssltest/
- **MySSL**: https://myssl.com/
- **证书查看器**: https://crt.sh/

### 7.3 命令行验证

```bash
# 检查证书信息
openssl x509 -in /etc/letsencrypt/live/blog.lazyyoun.xyz/fullchain.pem -noout -text

# 检查证书有效期
openssl x509 -in /etc/letsencrypt/live/blog.lazyyoun.xyz/fullchain.pem -noout -dates

# 测试 HTTPS 连接
curl -I https://blog.lazyyoun.xyz
```

---

## 📚 八、参考资料

- [Certbot 官方文档](https://certbot.eff.org/)
- [Let's Encrypt](https://letsencrypt.org/)
- [阿里云 DNS 文档](https://help.aliyun.com/document_detail/29776.html)
- [Nginx SSL 配置](https://nginx.org/en/docs/http/configuring_https_servers.html)
- [Certbot 阿里云 DNS 插件](https://github.com/tengattack/certbot-dns-aliyun)

---

## 🎯 九、快速命令汇总

```bash
# 1. 安装 certbot
yum install -y certbot python3-certbot-nginx

# 2. 申请证书
certbot certonly -d blog.lazyyoun.xyz --manual --preferred-challenges dns

# 3. 验证 DNS
dig +short TXT _acme-challenge.blog.lazyyoun.xyz @8.8.8.8

# 4. 测试 Nginx 配置
nginx -t

# 5. 重载 Nginx
nginx -s reload

# 6. 查看证书有效期
openssl x509 -in /etc/letsencrypt/live/blog.lazyyoun.xyz/fullchain.pem -noout -dates

# 7. 续期证书
certbot certonly -d blog.lazyyoun.xyz --manual --preferred-challenges dns
nginx -s reload
```

---

## ✅ 十、申请成功检查清单

- [ ] Certbot 已安装
- [ ] 执行 certbot 命令获取 TXT 值
- [ ] 在阿里云 DNS 添加 TXT 记录
- [ ] 等待 DNS 生效（1-5 分钟）
- [ ] 验证 DNS 记录（使用 dig 或 Google Toolbox）
- [ ] 在 certbot 中按回车继续
- [ ] 证书成功生成（查看输出信息）
- [ ] 配置 Nginx 使用证书
- [ ] 测试 Nginx 配置 (`nginx -t`)
- [ ] 重载 Nginx (`nginx -s reload`)
- [ ] 验证 HTTPS 访问 (`curl -I https://blog.lazyyoun.xyz`)
- [ ] 设置续期提醒（到期前 30 天）

---

*本文档基于 2026-03-23 实际申请流程整理*
*博客地址：https://blog.lazyyoun.xyz*

blog.lazyyoun.xyz HTTPS 证书申请完整指南

---
title: 如何通过程序调用 OpenClaw Agent 实现自动化任务
date: 2026-03-22
tags: [OpenClaw, API, 自动化，Python]
category: 开发教程
---

# 如何通过程序调用 OpenClaw Agent 实现自动化任务

> 💡 **问题背景**：如何通过代码调用 OpenClaw Agent，而不是只能通过 WebUI 对话？本文介绍多种编程方式调用 OpenClaw，实现调研、报告生成等自动化任务。

---

## 🎯 一、调用方式总览

| 方式 | 适用场景 | 难度 |
|------|---------|------|
| CLI 命令 | 脚本调用 | ⭐ |
| Python SDK | 深度集成 | ⭐⭐⭐ |
| Gateway WebSocket | 实时交互 | ⭐⭐⭐⭐ |
| sessions_spawn 工具 | 子任务执行 | ⭐⭐ |

---

## 🔧 二、CLI 命令调用（推荐）

### 2.1 基础用法

```bash
# 执行单个任务
openclaw agent --agent main --message "调研 AI 最新发展" --json

# 指定会话
openclaw agent --session-id abc123 --message "继续调研" --json

# 设置思考级别
openclaw agent --thinking high --message "生成架构设计" --json
```

### 2.2 Python 封装

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
OpenClaw Agent CLI 封装
"""

import subprocess
import json
from typing import Dict, Any, Optional

class OpenClawAgent:
    """OpenClaw Agent 调用封装"""
    
    def __init__(self, agent_id: str = "main"):
        self.agent_id = agent_id
    
    def run(self, 
            message: str, 
            thinking: str = "medium",
            timeout: int = 600) -> Dict[str, Any]:
        """
        执行 Agent 任务
        
        Args:
            message: 任务描述
            thinking: 思考级别 (off/minimal/low/medium/high/xhigh)
            timeout: 超时时间（秒）
            
        Returns:
            执行结果
        """
        cmd = [
            "openclaw", "agent",
            "--agent", self.agent_id,
            "--message", message,
            "--thinking", thinking,
            "--timeout", str(timeout),
            "--json"
        ]
        
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=timeout + 30
        )
        
        if result.returncode != 0:
            return {
                "success": False,
                "error": result.stderr
            }
        
        try:
            return json.loads(result.stdout)
        except json.JSONDecodeError:
            return {
                "success": True,
                "raw": result.stdout
            }
    
    def run_with_session(self,
                        session_id: str,
                        message: str,
                        **kwargs) -> Dict[str, Any]:
        """在指定会话中执行"""
        cmd = [
            "openclaw", "agent",
            "--agent", self.agent_id,
            "--session-id", session_id,
            "--message", message,
            "--json"
        ]
        # ... 同上
        
        return self._run_cmd(cmd)


# 使用示例
if __name__ == "__main__":
    agent = OpenClawAgent()
    
    # 执行调研任务
    result = agent.run("调研 2026 年 AI Agent 最新发展动态")
    
    if result.get("success"):
        print("✅ 调研完成")
        print(result.get("raw", result))
    else:
        print("❌ 调研失败:", result.get("error"))
```

### 2.3 实际案例：自动化调研

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
自动化调研报告生成
"""

from openclaw_agent import OpenClawAgent
import json
from datetime import datetime

class ResearchAgent:
    """研究 Agent"""
    
    def __init__(self):
        self.agent = OpenClawAgent()
        self.session_id = None
    
    def research(self, topic: str) -> dict:
        """
        执行完整调研流程
        """
        print(f"🔍 开始调研：{topic}")
        
        # 步骤 1：生成大纲
        print("\n📋 步骤 1: 生成调研大纲")
        outline_result = self.agent.run(
            f"为'{topic}'生成详细的调研大纲，列出主要方向"
        )
        
        # 步骤 2：分方向调研
        print("\n📊 步骤 2: 分方向深入调研")
        research_results = []
        
        # 这里可以解析大纲，然后对每个方向执行调研
        for direction in ["技术趋势", "市场动态", "主要玩家"]:
            result = self.agent.run(
                f"调研{topic}的{direction}，提供详细数据和案例"
            )
            research_results.append({
                "direction": direction,
                "result": result
            })
        
        # 步骤 3：生成报告
        print("\n📝 步骤 3: 生成完整报告")
        report_result = self.agent.run(
            f"根据前面的调研，生成'{topic}'的完整调研报告，包含：\n"
            "1. 执行摘要\n"
            "2. 技术趋势\n"
            "3. 市场分析\n"
            "4. 主要玩家\n"
            "5. 结论和建议"
        )
        
        return {
            "topic": topic,
            "timestamp": datetime.now().isoformat(),
            "outline": outline_result,
            "research": research_results,
            "report": report_result
        }


if __name__ == "__main__":
    researcher = ResearchAgent()
    report = researcher.research("AI Agent 框架")
    
    # 保存报告
    with open(f"report_{datetime.now().strftime('%Y%m%d')}.json", "w") as f:
        json.dump(report, f, ensure_ascii=False, indent=2)
    
    print("\n✅ 报告已保存！")
```

---

## 🌐 三、Gateway WebSocket 调用

### 3.1 连接 Gateway

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
通过 WebSocket 连接 OpenClaw Gateway
"""

import asyncio
import json
import websockets

class OpenClawGateway:
    """OpenClaw Gateway WebSocket 客户端"""
    
    def __init__(self, 
                 url: str = "ws://localhost:18789",
                 token: str = None):
        self.url = url
        self.token = token
        self.ws = None
        self.message_id = 0
    
    async def connect(self):
        """连接到 Gateway"""
        self.ws = await websockets.connect(self.url)
        
        # 发送连接请求
        connect_msg = {
            "type": "req",
            "id": self._gen_id(),
            "method": "connect",
            "params": {
                "client": {
                    "id": "python-client",
                    "version": "1.0.0"
                },
                "role": "operator",
                "scopes": ["operator.read", "operator.write"],
                "auth": {"token": self.token} if self.token else {}
            }
        }
        
        await self.ws.send(json.dumps(connect_msg))
        response = await self.ws.recv()
        print("连接成功:", json.loads(response))
    
    async def send_message(self, 
                          message: str,
                          agent_id: str = "main") -> dict:
        """发送消息给 Agent"""
        msg = {
            "type": "req",
            "id": self._gen_id(),
            "method": "agent.send",
            "params": {
                "agent": agent_id,
                "message": message
            }
        }
        
        await self.ws.send(json.dumps(msg))
        response = await self.ws.recv()
        return json.loads(response)
    
    def _gen_id(self) -> str:
        self.message_id += 1
        return f"msg-{self.message_id}"
    
    async def close(self):
        if self.ws:
            await self.ws.close()


# 使用示例
async def main():
    gateway = OpenClawGateway(token="your-token")
    await gateway.connect()
    
    # 执行任务
    result = await gateway.send_message(
        "调研最新 AI 技术趋势"
    )
    
    print("执行结果:", result)
    
    await gateway.close()

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🛠️ 四、sessions_spawn 工具调用

### 4.1 创建子 Agent

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
使用 sessions_spawn 创建子 Agent 执行任务
"""

import subprocess
import json

def spawn_agent_task(task: str, 
                    agent_id: str = "main",
                    mode: str = "run") -> dict:
    """
    创建子 Agent 任务
    
    Args:
        task: 任务描述
        agent_id: Agent ID
        mode: run（一次性）或 session（持久会话）
    """
    cmd = [
        "openclaw",
        "sessions", "spawn",
        "--task", task,
        "--mode", mode,
        "--agent", agent_id,
        "--json"
    ]
    
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True
    )
    
    return json.loads(result.stdout)


# 使用示例
if __name__ == "__main__":
    # 创建调研任务
    result = spawn_agent_task(
        "调研 2026 年 AI Agent 发展趋势，生成详细报告",
        agent_id="main",
        mode="run"
    )
    
    print("任务创建成功:", result)
    print("任务 ID:", result.get("sessionKey"))
```

### 4.2 查询任务状态

```python
def check_task_status(session_key: str) -> dict:
    """查询任务状态"""
    cmd = [
        "openclaw",
        "sessions", "history",
        "--session-key", session_key,
        "--json"
    ]
    
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True
    )
    
    return json.loads(result.stdout)


# 轮询任务状态
import time

def wait_for_completion(session_key: str, 
                       timeout: int = 1800) -> dict:
    """等待任务完成"""
    start_time = time.time()
    
    while time.time() - start_time < timeout:
        status = check_task_status(session_key)
        
        if status.get("completed"):
            return status
        
        print(f"任务进行中... {time.time() - start_time:.0f}s")
        time.sleep(10)
    
    return {"error": "超时"}
```

---

## 📊 五、完整案例：自动化报告生成系统

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
自动化报告生成系统
通过 OpenClaw Agent 实现调研、分析、报告生成全流程
"""

import json
import time
from datetime import datetime
from pathlib import Path
from openclaw_agent import OpenClawAgent

class ReportGenerator:
    """报告生成器"""
    
    def __init__(self, output_dir: str = "./reports"):
        self.agent = OpenClawAgent()
        self.output_dir = Path(output_dir)
        self.output_dir.mkdir(exist_ok=True)
    
    def generate_report(self, 
                       topic: str,
                       sections: list = None) -> dict:
        """
        生成完整报告
        
        Args:
            topic: 报告主题
            sections: 章节列表（可选，默认自动生成）
        """
        print(f"🚀 开始生成报告：{topic}")
        
        report = {
            "topic": topic,
            "created_at": datetime.now().isoformat(),
            "sections": []
        }
        
        # 步骤 1：生成大纲
        print("\n📋 生成大纲...")
        outline = self._generate_outline(topic)
        report["outline"] = outline
        
        # 步骤 2：分章节撰写
        sections = sections or outline.get("sections", [])
        for i, section in enumerate(sections, 1):
            print(f"\n📝 撰写章节 {i}/{len(sections)}: {section}")
            content = self._write_section(topic, section)
            report["sections"].append({
                "title": section,
                "content": content
            })
        
        # 步骤 3：生成摘要和结论
        print("\n📊 生成摘要和结论...")
        summary = self._generate_summary(report)
        report["summary"] = summary
        
        # 保存报告
        self._save_report(report)
        
        return report
    
    def _generate_outline(self, topic: str) -> dict:
        """生成大纲"""
        result = self.agent.run(
            f"为'{topic}'生成详细的报告大纲，返回 JSON 格式：\n"
            "{{\"sections\": [\"章节 1\", \"章节 2\", ...]}}"
        )
        return result
    
    def _write_section(self, topic: str, section: str) -> str:
        """撰写章节"""
        result = self.agent.run(
            f"撰写'{topic}'报告中'{section}'章节的内容，要求：\n"
            "1. 详细、专业\n"
            "2. 包含数据和案例\n"
            "3. 至少 500 字"
        )
        return result.get("raw", "")
    
    def _generate_summary(self, report: dict) -> str:
        """生成摘要"""
        result = self.agent.run(
            f"根据以下报告内容，生成 300 字的执行摘要和结论：\n"
            f"主题：{report['topic']}\n"
            f"章节：{len(report['sections'])}个"
        )
        return result.get("raw", "")
    
    def _save_report(self, report: dict):
        """保存报告"""
        filename = f"{report['topic'][:20]}_{datetime.now().strftime('%Y%m%d')}.json"
        filepath = self.output_dir / filename
        
        with open(filepath, "w", encoding="utf-8") as f:
            json.dump(report, f, ensure_ascii=False, indent=2)
        
        print(f"\n✅ 报告已保存：{filepath}")


if __name__ == "__main__":
    generator = ReportGenerator()
    
    report = generator.generate_report(
        "2026 年 AI Agent 发展趋势",
        sections=[
            "技术趋势",
            "市场分析",
            "主要玩家",
            "应用场景",
            "挑战与机遇"
        ]
    )
    
    print("\n🎉 报告生成完成！")
```

---

## 🎯 六、最佳实践

### 6.1 错误处理

```python
def safe_agent_call(message: str, retries: int = 3) -> dict:
    """带重试的安全调用"""
    for i in range(retries):
        try:
            result = agent.run(message)
            if result.get("success"):
                return result
        except Exception as e:
            print(f"第{i+1}次失败：{e}")
            time.sleep(2 ** i)  # 指数退避
    
    return {"success": False, "error": "多次重试失败"}
```

### 6.2 进度追踪

```python
def track_progress(task_id: str):
    """追踪任务进度"""
    while True:
        status = check_task_status(task_id)
        print(f"进度：{status.get('progress', 0)}%")
        
        if status.get("completed"):
            break
        
        time.sleep(5)
```

### 6.3 成本控制

```python
# 设置 token 预算
def budget_aware_call(message: str, max_tokens: int = 10000):
    """带 token 预算的调用"""
    result = agent.run(
        message,
        extra_args={"maxTokens": max_tokens}
    )
    print(f"消耗 token: {result.get('usage', {})}")
    return result
```

---

## 📚 七、参考资料

- [OpenClaw CLI 文档](https://docs.openclaw.ai/zh-CN/cli)
- [Gateway 协议](https://docs.openclaw.ai/zh-CN/gateway/protocol)
- [Agent 配置](https://docs.openclaw.ai/zh-CN/agents)
- [own-code-dashboard 项目](http://blog.lazyyoun.xyz/)

---

*本文示例代码：`~/Documents/own-code-dashboard/scripts/openclaw-examples/`*

如何通过程序调用 OpenClaw Agent 实现自动化任务

---
title: OpenClaw 深度调研：为什么复杂任务只执行十几轮就结束？
date: 2026-03-22
tags: [OpenClaw, AI Agent, 自动化]
category: 技术调研
---

# OpenClaw 深度调研：为什么复杂任务只执行十几轮就结束？

> 💡 **问题背景**：在使用 OpenClaw 执行复杂任务时，发现即使是很复杂的任务，Agent 通常也只执行十几轮 tool calls 就结束了，并且会输出类似"完成了 15% 的任务，接下来要干 XX"这样的总结。这是设计如此还是限制？本文深入调研 OpenClaw 的 Agent 执行机制。

---

## 🔍 一、现象观察

### 1.1 典型执行流程

```bash
# 执行一个复杂任务
openclaw agent --agent main --message "调研 AI Agent 最新发展动态，生成详细报告"
```

**执行结果**：
- Tool Calls: 10-15 次
- 执行时间：2-5 分钟
- 输出：`完成了 15% 的任务，接下来需要继续调研 XX 方向...`

### 1.2 问题核心

1. **为什么只执行十几轮就结束？**
2. **为什么会有完成度百分比？**
3. **如何让它继续执行直到完成任务？**

---

## 📊 二、OpenClaw Agent 执行机制

### 2.1 Agent 执行流程

```
用户请求 → Gateway → Agent → 规划 → 执行 Tool → 观察结果 → 再规划 → ...
                                    ↑                              ↓
                                    └────────── 循环 ──────────────┘
```

### 2.2 关键限制因素

#### 2.2.1 Token 限制

OpenClaw 使用 LLM 进行规划，每次调用都有 token 限制：

| 模型 | 上下文窗口 | 实际可用 |
|------|-----------|---------|
| qwen3.5-plus | 1M tokens | ~800K |
| glm-5 | 256K tokens | ~200K |

**影响**：
- 每次 tool call 都会消耗 token
- 历史对话会累积占用上下文
- 达到限制后必须总结并结束当前回合

#### 2.2.2 超时设置

```bash
# 默认超时 600 秒（10 分钟）
openclaw agent --timeout 1800 --message "复杂任务"
```

**影响**：
- 复杂任务可能超时
- 每个 tool call 也有独立超时
- 超时后 Agent 会总结当前进度并退出

#### 2.2.3 成本考虑

每次 tool call 都产生成本：
- LLM 调用费用
- 外部 API 调用费用
- 计算资源消耗

**OpenClaw 设计哲学**：
> "I don't just autocomplete—I auto-commit (emotionally), then ask you to review (logically)."

即：**Agent 不应该无限执行，应该在适当时候停下来让人类确认**

---

## 🛠️ 三、解决方案

### 3.1 方案一：多轮执行（推荐）

```bash
# 第一轮：初步调研
openclaw agent --message "调研 AI Agent 发展动态，先完成大纲和主要方向"

# 第二轮：深入某个方向
openclaw agent --message "继续深入调研 XX 方向，补充详细信息"

# 第三轮：生成报告
openclaw agent --message "根据前面的调研，生成完整报告"
```

**优点**：
- 每轮都有明确目标
- 可以人工介入调整方向
- 避免 token 超限

### 3.2 方案二：使用 Cron 定时任务

```bash
# 创建定时任务，每 30 分钟执行一次
openclaw cron add \
  --name "ai-research" \
  --every "30m" \
  --message "继续 AI Agent 调研任务，每次深入一个方向"
```

**优点**：
- 自动化执行
- 可以跨多天完成大任务
- 每次执行都有进度记录

### 3.3 方案三：调整 Agent 配置

编辑 `~/.openclaw/openclaw.json`：

```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "model": "dashscope/qwen3.5-plus",
        "maxConcurrent": 8,
        "compaction": {
          "mode": "aggressive"  // 更激进的上下文压缩
        }
      }
    ]
  }
}
```

**影响**：
- 增加并发数可以加快执行
- 激进的 compaction 可以延长执行轮数
- 但可能丢失重要上下文

---

## 📈 四、最佳实践

### 4.1 任务分解

❌ **错误做法**：
```
"帮我完成一个完整的 AI 行业调研报告"
```

✅ **正确做法**：
```
1. "列出 AI 行业调研的大纲和主要方向"
2. "调研方向 1：大模型最新进展"
3. "调研方向 2：Agent 框架对比"
4. "生成完整报告"
```

### 4.2 使用 Thinking 级别

```bash
# 简单任务：关闭思考
openclaw agent --thinking off --message "查询天气"

# 中等任务：低思考
openclaw agent --thinking low --message "分析日志"

# 复杂任务：高思考
openclaw agent --thinking high --message "生成架构设计"
```

### 4.3 进度追踪

```bash
# 查看会话历史
openclaw sessions list --active 60

# 查看特定会话
openclaw sessions history --session-id xxx
```

---

## 🎯 五、总结

### 5.1 核心原因

| 原因 | 说明 | 可调整 |
|------|------|--------|
| Token 限制 | LLM 上下文窗口有限 | ⚠️ 部分可调 |
| 超时设置 | 默认 10 分钟超时 | ✅ 可调 |
| 设计理念 | 人机协作，非完全自主 | ⚠️ 不建议改 |
| 成本考虑 | 每次调用都有成本 | ⚠️ 客观限制 |

### 5.2 建议

1. **接受设计哲学**：OpenClaw 设计为"人机协作"，不是完全自主 Agent
2. **任务分解**：将大任务拆分为多个小任务
3. **使用 Cron**：利用定时任务实现长期执行
4. **人工介入**：在关键节点人工确认方向

### 5.3 未来展望

OpenClaw 的这种方式实际上是**更负责任的设计**：
- ✅ 避免 Agent 失控执行
- ✅ 节省成本和资源
- ✅ 保持人类对关键决策的控制

---

## 📚 参考资料

- [OpenClaw 官方文档](https://docs.openclaw.ai)
- [Agent 配置指南](https://docs.openclaw.ai/zh-CN/agents)
- [Gateway 协议](https://docs.openclaw.ai/zh-CN/gateway/protocol)
- [CLI 使用手册](https://docs.openclaw.ai/zh-CN/cli)

---

*本文基于 OpenClaw v2026.3.13 调研*