OpenClaw 提示词与工作流 —— 结构化指令、工作流设计、最佳实践

# ❌ 糟糕的指令
openclaw "优化这段代码"

# ✅ 好的指令
openclaw -f main.py "将 main.py 中所有使用字符串拼接的 SQL 查询
改为参数化查询，使用 sqlite3 的 ? 占位符语法"

# ✅ 带约束的指令
openclaw -f api.py "重构路由函数，要求：
1. 使用装饰器处理认证，而不是在每个函数中重复
2. 不要改变现有的 URL 路径
3. 保持函数签名不变（向后兼容）
4. 添加类型注解
5. 不要引入新的第三方依赖"

# ✅ 指定输出格式
openclaw -f schema.py "分析这个文件中的数据库模型，
输出格式为：
- 表名
  - 字段1: 类型 (约束)
  - 字段2: 类型 (约束)
- 外键关系：表A.字段 -> 表B.字段"

# ✅ 角色 + 任务 + 约束 + 格式
openclaw "你是一位资深的 Python 安全审计专家。请审查以下代码中的安全漏洞，
按照以下格式输出：
【高危】描述 - 修复建议
【中危】描述 - 修复建议
【低危】描述 - 修复建议

代码文件：
$(cat auth.py)"

C - Context（背景）：任务的背景信息
R - Role（角色）：AI 扮演的角色
A - Action（行动）：具体要做什么
F - Format（格式）：输出格式要求
T - Target（目标）：期望达到的目标

# CRAFT 模板实战
openclaw "【C】这是一个使用 Flask + SQLAlchemy 的用户管理系统，
目前存在 N+1 查询问题。

【R】你是一位数据库性能优化专家。

【A】请分析以下代码中的查询模式，
1. 识别所有 N+1 查询的位置
2. 为每个问题提供优化方案（使用 joinedload 或 subqueryload）
3. 给出优化后的代码

【F】请按以下格式输出：
问题 #1：[文件:行号]
  原始查询：...
  优化方案：...
  优化后代码：...

【T】目标是将页面加载时间从 2s 降低到 200ms 以内。

代码文件：
$(cat models/user.py)
$(cat routes/user.py)"

# 代码生成标准模板
openclaw "【功能】实现一个带限流和重试的 HTTP 客户端

【技术栈】Python 3.10+、aiohttp、tenacity

【要求】
1. 支持 GET/POST/PUT/DELETE 方法
2. 内置指数退避重试（最多 3 次）
3. 支持每分钟 60 次的限流
4. 所有方法都有完整的类型注解
5. 包含单元测试示例

【输出】完整可运行的代码 + 使用示例"

# 代码审查标准模板
openclaw "【审查范围】以下文件的代码变更

【审查维度】
1. 正确性：逻辑错误、边界条件、异常处理
2. 安全性：SQL 注入、XSS、认证绕过
3. 性能：复杂度、内存泄漏、N+1 查询
4. 可维护性：命名、注释、代码重复
5. 测试：测试覆盖率、边界用例

【严重级别】CRITICAL / HIGH / MEDIUM / LOW / INFO

【格式】
[严重级别] [维度] 问题描述
  位置：文件:行号
  建议：修复方案

代码：
$(cat api/auth.py)
$(cat api/users.py)"

# 重构标准模板
openclaw "【重构目标】将单体函数拆分为独立模块

【当前状态】以下函数承担了太多职责：
$(cat services/order_service.py)

【重构要求】
1. 拆分为：订单创建、订单支付、订单通知 三个独立服务
2. 使用依赖注入模式
3. 保持现有 API 接口不变
4. 添加单元测试
5. 输出完整的文件结构

【约束】
- 不改变数据库 schema
- 不改变外部 API 调用方式
- 使用 Python 3.10+ 语法"

┌──────────────────────────────────────────────────────────┐
│              上下文窗口分配策略                            │
├──────────────────┬──────────────┬────────────────────────┤
│ 部分             │ 预估 Token   │ 占比                   │
├──────────────────┼──────────────┼────────────────────────┤
│ 系统提示词       │ ~1,000       │ 2-3%                   │
│ 指令内容         │ ~500-2,000   │ 1-5%                   │
│ 文件内容         │ ~10,000-30K  │ 30-75%                 │
│ 对话历史         │ ~5,000-15K   │ 15-40%                 │
│ 输出预留         │ ~5,000-10K   │ 15-25%                 │
└──────────────────┴──────────────┴────────────────────────┘

# 技巧 1：只传递必要的代码片段
# ❌ 传递整个文件
openclaw -f huge_file.py "修改第 150-160 行的逻辑"

# ✅ 提取相关代码片段
sed -n '140,170p' huge_file.py | openclaw "修改这段代码中的循环逻辑"

# 技巧 2：使用 --quiet 减少输出 token
openclaw --quiet "生成快速排序" > sort.py

# 技巧 3：分步处理大文件
openclaw "列出 main.py 中所有的函数定义" > functions.txt
# 然后针对每个函数单独处理

# 交互模式中管理上下文
openclaw

# 清空不必要的历史，释放上下文
> /clear

# 保存重要对话，后续可以加载
> /save important_design.md

# 加载之前的对话
> /load important_design.md

# 查看当前上下文使用情况（如果工具支持）
> /config

#!/bin/bash
# 分块处理大型代码库

# 第一步：分析项目结构
openclaw "列出 src/ 目录下所有 Python 文件及其依赖关系" > structure.md

# 第二步：逐个模块处理
for module in api services models; do
  echo "处理 $module 模块..."
  openclaw -f "src/$module/*.py" \
    "为这个模块添加完整的类型注解和文档字符串" \
    > "docs/${module}_annotated.py"
done

# 第三步：整合结果
openclaw "根据以下模块文档，生成完整的项目 API 文档" \
  -f "docs/*.py" > API_DOCUMENTATION.md

┌──────────────────────────────────────────────────────────┐
│                  工作流设计三原则                          │
│                                                          │
│  1. 原子性：每个步骤只做一件事                            │
│     - 好的：「提取函数签名」→「添加类型注解」→「生成文档」 │
│     - 坏的：「分析代码并添加类型注解和文档和单元测试」      │
│                                                          │
│  2. 顺序性：步骤之间有清晰的依赖关系                       │
│     - A 的输出是 B 的输入                                 │
│     - 并行步骤可以独立执行                                │
│                                                          │
│  3. 可验证性：每个步骤的结果都可以检查                      │
│     - 语法检查、测试运行、diff 审查                        │
│     - 失败时能够快速定位问题                              │
└──────────────────────────────────────────────────────────┘

需求 → 分析 → 设计 → 编码 → 测试 → 文档 → 完成

每个阶段的输出作为下一阶段的输入。

#!/bin/bash
# 线性工作流：从需求到文档

# 阶段 1：需求分析
openclaw "基于以下需求，列出功能点和 API 端点：
用户注册、登录、修改密码、查看个人信息" > requirements.md

# 阶段 2：API 设计
openclaw -f requirements.md "设计 RESTful API，输出 OpenAPI 规范" > api_spec.yaml

# 阶段 3：生成骨架代码
openclaw -f api_spec.yaml "基于 OpenAPI 规范生成 Flask 骨架代码" > app.py

# 阶段 4：实现业务逻辑
openclaw -f app.py "实现用户注册和登录的业务逻辑"

# 阶段 5：生成测试
openclaw -f app.py "为注册和登录功能生成 pytest 测试用例" > test_app.py

# 阶段 6：生成文档
openclaw -f app.py -f api_spec.yaml "生成 API 使用文档" > USAGE.md

主任务拆解
  ├── 子任务 A（独立）
  ├── 子任务 B（独立）
  └── 子任务 C（独立）
        ↓
      合并结果

#!/bin/bash
# 并行工作流：同时处理多个文件

# 同时审查多个文件（利用后台任务）
openclaw "审查 auth.py 的安全性" &
openclaw "审查 routes.py 的正确性" &
openclaw "审查 models.py 的完整性" &
wait  # 等待所有任务完成

# 合并结果
cat *.review > full_review.md

初始版本 → 审查 → 修复 → 测试 → 优化 → 最终版本
     ↑                                        │
     └──────────────── 反馈循环 ←──────────────┘

#!/bin/bash
# 迭代优化工作流

MAX_ITERATIONS=3
for i in $(seq 1 $MAX_ITERATIONS); do
  echo "=== 第 $i 轮迭代 ==="

  # 1. 运行测试
  if python -m pytest tests/ -q; then
    echo "测试通过！"
    break
  fi

  # 2. 让 AI 分析失败原因
  openclaw "分析以下测试失败的原因，给出修复方案：
$(python -m pytest tests/ --tb=short 2>&1)" > fix_plan.md

  # 3. 应用修复
  openclaw -f fix_plan.md -f src/*.py "根据修复计划修改代码"

  # 4. 验证
  python -m pytest tests/ -q
done

#!/bin/bash
# 完整工作流：从零搭建用户管理 API

echo "=== 第 1 步：需求分析 ==="
openclaw "设计一个用户管理系统的 API，包含：
1. 用户注册（邮箱、密码）
2. 用户登录（JWT token）
3. 用户资料 CRUD
4. 密码重置

输出：API 端点列表、请求/响应格式、错误码" > api_design.md

echo "=== 第 2 步：数据模型设计 ==="
openclaw -f api_design.md "设计 SQLAlchemy 数据模型，包含：
- User 表（id, email, password_hash, created_at, updated_at）
- Profile 表（user_id, name, bio, avatar_url）
输出完整的 models.py" > models.py

echo "=== 第 3 步：生成骨架 ==="
openclaw -f api_design.md -f models.py "生成 Flask 应用骨架：
- app.py（应用入口）
- routes/auth.py（认证路由）
- routes/users.py（用户路由）
- config.py（配置）
- requirements.txt" > skeleton.zip

echo "=== 第 4 步：实现核心逻辑 ==="
openclaw -f routes/auth.py -f models.py "实现注册和登录的完整逻辑：
- 密码使用 bcrypt 哈希
- JWT token 生成和验证
- 输入验证和错误处理"

echo "=== 第 5 步：生成测试 ==="
openclaw -f routes/ -f models.py "生成完整的 pytest 测试：
- 单元测试（模型验证）
- 集成测试（API 端点）
- 边界用例测试" > tests/

echo "=== 第 6 步：生成文档 ==="
openclaw -f api_design.md -f routes/ "生成 Swagger/OpenAPI 文档和使用手册"

echo "=== 完成！==="

#!/bin/bash
# 工作流：Python 2 到 Python 3 的迁移

# 第一步：扫描需要修改的内容
openclaw "扫描以下 Python 2 代码，列出需要迁移的问题：
1. print 语句 → print 函数
2. unicode 处理
3. xrange → range
4. 除法语义变化
5. 迭代器 .iteritems() → .items()
6. except 语法
$(find src/ -name '*.py' -exec cat {} +)" > migration_report.md

# 第二步：分类处理
grep "print 语句" migration_report.md | while read -r issue; do
  file=$(echo "$issue" | cut -d: -f1)
  openclaw -f "$file" "将所有 print 语句改为 print 函数调用"
done

# 第三步：运行迁移工具
2to3 -w src/

# 第四步：AI 辅助修复
openclaw "运行以下测试，分析失败原因并修复：
$(python -m pytest tests/ --tb=short 2>&1)"

# 第五步：验证
python -m pytest tests/ -v

#!/bin/bash
# 工作流：为现有项目添加测试

# 第一步：分析未覆盖的代码
coverage run -m pytest tests/
coverage report --show-missing > coverage_report.txt

# 第二步：逐个模块生成测试
grep -E "^[a-z]" coverage_report.txt | while read -r line; do
  file=$(echo "$line" | awk '{print $1}')
  missing=$(echo "$line" | awk '{print $NF}')

  openclaw -f "$file" "为以下未覆盖的代码行生成测试用例：
行号：$missing
要求：使用 pytest，包含正常路径和异常路径" >> "tests/test_${file%.py}.py"
done

# 第三步：运行并验证
coverage run -m pytest tests/
coverage report
coverage html

# Makefile：将 OpenClaw 集成到构建流程中

.PHONY: review test docs refactor clean

# 代码审查
review:
	openclaw --quiet "审查所有 Python 文件的代码质量" \
		-f "src/*.py" -f "tests/*.py" > review.md
	@echo "审查报告已生成: review.md"

# 生成文档
docs:
	openclaw --quiet "为以下代码生成 API 文档" \
		-f "src/*.py" --format markdown > docs/api.md
	@echo "文档已生成: docs/api.md"

# 自动重构
refactor:
	openclaw -f "src/*.py" "将所有使用 dict 传参的函数\n\
		改为使用 dataclass 或 TypedDict"
	@echo "重构完成"

# 生成测试
generate-tests:
	openclaw -f "src/services/*.py" \
		"为这些服务类生成 pytest 测试用例" \
		> tests/test_services.py
	@echo "测试已生成: tests/test_services.py"

# 完整管线
ci: review docs test
	@echo "CI 管线完成"

#!/bin/bash
# .git/hooks/pre-commit
# 提交前自动运行代码审查

echo "🔍 运行 AI 代码审查..."

# 获取本次变更的文件
changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')

if [ -n "$changed_files" ]; then
  # 对变更文件进行审查
  for file in $changed_files; do
    openclaw --quiet "审查以下变更的代码，指出潜在问题" \
      -f "$file" >> /tmp/ai_review_$$
  done

  # 如果有严重问题，阻止提交
  if grep -q "【严重】\|【高危】" /tmp/ai_review_$$; then
    echo "❌ 发现严重问题，请修复后重新提交"
    cat /tmp/ai_review_$$
    rm /tmp/ai_review_$$
    exit 1
  fi

  echo "✅ 代码审查通过"
  rm /tmp/ai_review_$$
fi

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup OpenClaw
        run: pip install openclaw

      - name: Run AI Review
        env:
          OPENCLAW_API_KEY: ${{ secrets.OPENCLAW_API_KEY }}
        run: |
          changed_files=$(git diff --name-only HEAD~1 HEAD | grep '\.py$' || true)
          if [ -n "$changed_files" ]; then
            for file in $changed_files; do
              openclaw --quiet "审查以下代码变更" \
                -f "$file" >> review.md
            done
          fi

      - name: Post Review Comment
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## AI Code Review\n\n' + review
            });

#!/bin/bash
# crontab 条目：每天凌晨 2 点运行代码健康检查
# 0 2 * * * /home/user/scripts/daily_health_check.sh

#!/bin/bash
# daily_health_check.sh

LOG_DIR="/var/log/ai-health-check"
mkdir -p "$LOG_DIR"
DATE=$(date +%Y%m%d)

echo "=== 每日代码健康检查 ===" >> "$LOG_DIR/health_$DATE.log"

# 检查代码质量
openclaw --quiet "分析 src/ 目录下的代码，输出质量报告：
1. 代码重复率
2. 函数复杂度
3. 未使用的导入
4. 命名规范问题" >> "$LOG_DIR/health_$DATE.log"

# 检查依赖安全
openclaw --quiet "检查 requirements.txt 中是否有已知安全漏洞的依赖" \
  >> "$LOG_DIR/health_$DATE.log"

# 检查测试覆盖
openclaw --quiet "分析测试覆盖情况，列出未覆盖的关键函数" \
  >> "$LOG_DIR/health_$DATE.log"

# 发送通知（如果有问题）
if grep -q "【高危】\|【严重】" "$LOG_DIR/health_$DATE.log"; then
  curl -X POST "https://hooks.slack.com/services/xxx" \
    -d '{"text":"代码健康检查发现问题，请查看日志"}'
fi

# ~/.config/openclaw/templates.yaml
# 可复用的指令模板

templates:
  code_review:
    description: "代码审查"
    prompt: |
      你是一位资深的 {language} 开发工程师。请审查以下代码：

      审查维度：
      1. 正确性
      2. 安全性
      3. 性能
      4. 可维护性
      5. 测试覆盖

      输出格式：
      [级别] [维度] 问题描述
        位置：文件:行号
        建议：修复方案
    variables:
      - language

  add_tests:
    description: "生成测试用例"
    prompt: |
      为以下 {language} 代码生成完整的测试用例：

      要求：
      1. 正常路径测试
      2. 异常路径测试
      3. 边界条件测试
      4. 使用 {test_framework} 框架
    variables:
      - language
      - test_framework

  refactor:
    description: "代码重构"
    prompt: |
      重构以下代码，目标：{goal}

      约束：
      1. 保持外部接口不变
      2. 不改变业务逻辑
      3. 添加必要的注释
      4. 遵循 {style_guide} 规范
    variables:
      - goal
      - style_guide

  document:
    description: "生成文档"
    prompt: |
      为以下代码生成 {doc_type} 文档：

      包含：
      1. 功能概述
      2. API 说明（参数、返回值、异常）
      3. 使用示例
      4. 注意事项
    variables:
      - doc_type

#!/bin/bash
# use-template.sh：使用预定义模板

TEMPLATE_DIR="$HOME/.config/openclaw/templates"

use_template() {
  local template_name=$1
  shift

  local template_file="$TEMPLATE_DIR/${template_name}.txt"

  if [ ! -f "$template_file" ]; then
    echo "模板不存在: $template_file"
    return 1
  fi

  # 读取模板并替换变量
  local prompt=$(cat "$template_file")

  # 替换 $FILE 为实际文件内容
  if [ -n "$OPENCLAW_FILE" ]; then
    prompt=$(echo "$prompt" | sed "s|\$FILE|$(cat "$OPENCLAW_FILE")|g")
  fi

  # 执行
  openclaw "$prompt" "$@"
}

# 使用示例
export OPENCLAW_FILE="src/auth.py"
use_template code_review

# ./openclaw-templates.yaml（项目级模板）

project: "my-api-project"

templates:
  new_endpoint:
    prompt: |
      在 routes/ 目录下创建一个新的 API 端点：
      - 路径: {path}
      - 方法: {method}
      - 功能: {description}

      要求：
      1. 遵循项目现有的路由风格
      2. 使用项目统一的错误处理
      3. 添加请求/响应验证
      4. 编写对应的测试用例

  new_model:
    prompt: |
      在 models/ 目录下创建一个新的数据库模型：
      - 名称: {name}
      - 字段: {fields}
      - 关系: {relations}

      要求：
      1. 使用 SQLAlchemy 2.0 语法
      2. 添加迁移脚本
      3. 添加单元测试

# 策略 1：精简输入文件
# ❌ 包含所有注释和文档
openclaw -f huge_file.py "分析代码结构"

# ✅ 只传递核心代码
grep -v '^\s*#' huge_file.py | grep -v '^\s*$' | \
  openclaw "分析代码结构"

# 策略 2：分步请求，避免一次性处理太多
# ❌ 一次性做太多事
openclaw -f "src/*.py" "审查所有代码、生成文档、添加测试"

# ✅ 分步执行
openclaw -f "src/auth.py" "审查代码"
openclaw -f "src/auth.py" "生成文档"
openclaw -f "src/auth.py" "添加测试"

# 策略 1：选择更快的模型
openclaw --model gpt-4o-mini "快速任务"  # 速度快
openclaw --model gpt-4o "复杂任务"       # 质量好但慢

# 策略 2：设置合理的超时
openclaw --timeout 30 "简单任务"
openclaw --timeout 120 "复杂分析"

# 策略 3：利用缓存
# OpenClaw 的配置中启用缓存
# config.yaml:
# advanced:
#   cache:
#     enabled: true
#     dir: ~/.cache/openclaw
#     max_size: 500

# 策略 4：批量处理时使用并行
parallel --jobs 4 openclaw --quiet ::: \
  "审查 auth.py" \
  "审查 routes.py" \
  "审查 models.py" \
  "审查 config.py"

┌───────────────────────────────────────────────────────────┐
│                  Token 消耗估算表                          │
├──────────────────────┬───────────────┬────────────────────┤
│ 操作                 │ 输入 Token    │ 输出 Token         │
├──────────────────────┼───────────────┼────────────────────┤
│ 解释一段代码         │ ~500-2,000    │ ~500-1,000         │
│ 生成一个函数         │ ~200-500      │ ~500-2,000         │
│ 审查一个文件         │ ~2,000-8,000  │ ~1,000-3,000       │
│ 重构一个模块         │ ~5,000-15K    │ ~3,000-10K         │
│ 生成完整文档         │ ~3,000-10K    │ ~2,000-8,000       │
│ 端到端搭建 API       │ ~10K-30K      │ ~5,000-20K         │
└──────────────────────┴───────────────┴────────────────────┘

# ❌ 模糊指令
openclaw "优化这段代码"
# AI 可能会做你不需要的事情

# ✅ 具体指令
openclaw -f main.py "将 time complexity 从 O(n²) 优化到 O(n log n)，
使用排序 + 双指针方案，不要改变函数签名"

# ❌ 一次性加载太多文件
openclaw -f "src/**/*.py" "分析整个项目架构"
# 可能超出上下文窗口

# ✅ 分层次分析
openclaw "列出 src/ 目录的顶层结构"
openclaw -f "src/api/" "分析 api 模块的架构"
openclaw -f "src/services/" "分析 services 模块的架构"

# ❌ AI 生成代码后直接使用
openclaw "生成数据库迁移脚本" > migration.py
python manage.py migrate  # 可能失败！

# ✅ 生成后验证
openclaw "生成数据库迁移脚本" > migration.py
# 先检查语法
python -m py_compile migration.py
# 再 dry-run
python manage.py migrate --plan
# 确认无误后执行
python manage.py migrate

# ❌ 没有约束
openclaw "重写这个函数"

# ✅ 明确约束
openclaw "重写这个函数，要求：
- 保持完全相同的输入/输出行为
- 不要引入新的依赖
- 性能不能比原来差
- 添加类型注解
- 保持相同的错误处理方式"

# ❌ 不在工作流中保存中间结果
openclaw "分析代码" | openclaw "根据分析结果重构"
# 如果第二步失败，一切重来

# ✅ 保存中间结果
openclaw "分析代码" > analysis.md
# 检查 analysis.md
openclaw -f analysis.md "根据分析结果重构"
# 即使第二步失败，分析结果还在