OpenClaw 基础使用 —— 单任务与交互模式、命令执行、输出管理

openclaw [选项] "你的指令"

# 解释代码
openclaw "解释这段代码的作用：[x**2 for x in range(10)]"

# 生成代码
openclaw "用 Python 写一个计算斐波那契数列的函数"

# 修复 bug
openclaw "以下代码有什么问题？如何修复？
def divide(a, b):
    return a / b"

# 代码审查
openclaw "审查这段代码，指出潜在问题：
def get_user(user_id):
    conn = sqlite3.connect('db.sqlite')
    cursor = conn.cursor()
    cursor.execute(f'SELECT * FROM users WHERE id = {user_id}')
    return cursor.fetchone()"

$ openclaw "用 Python 写一个快速排序"

def quick_sort(arr):
    """快速排序算法"""
    if len(arr) <= 1:
        return arr

    pivot = arr[len(arr) // 2]
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]

    return quick_sort(left) + middle + quick_sort(right)

# 使用示例
if __name__ == "__main__":
    test = [3, 6, 8, 10, 1, 2, 1]
    print(f"原始: {test}")
    print(f"排序后: {quick_sort(test)}")

# 使用 -f 参数附加文件
openclaw -f main.py "分析这个文件的结构，指出可以优化的地方"

# 附加多个文件
openclaw -f models/user.py -f models/order.py \
  "检查这两个模型的关系，是否需要添加外键约束"

# 使用通配符
openclaw -f "src/*.py" "找出所有未使用的导入语句"

# 附加目录（递归扫描）
openclaw -d ./src "分析这个目录下的代码架构"

# --quiet：只输出结果，不显示额外信息
openclaw --quiet "生成一个 hello world 程序"

# --no-shell：禁止 Shell 执行
openclaw --no-shell "解释这段代码"

# --timeout：设置超时时间（秒）
openclaw --timeout 120 "分析这个 500 行的文件"

# --json：以 JSON 格式输出
openclaw --json "提取以下文本中的所有日期"

# --model：覆盖默认模型
openclaw --model gpt-4o-mini "写一段代码"

# 直接启动
openclaw

# 启动并附带初始指令
openclaw "帮我重构这个项目"

# 启动并附加文件
openclaw -f main.py -f config.py

┌──────────────────────────────────────────────────────────┐
│                    OpenClaw 交互模式                      │
│                                                          │
│  OpenClaw v2.1.0 | Provider: openai | Model: gpt-4o-mini │
│                                                          │
│  输入指令开始对话。输入 /help 查看可用命令。               │
│  输入 /exit 或 Ctrl+D 退出。                              │
│                                                          │
└──────────────────────────────────────────────────────────┘

> 帮我为这个项目添加一个日志系统

  🤖 我将为你添加一个基于 Python logging 模块的日志系统。

  步骤：
  1. 创建 logger.py 模块
  2. 配置不同级别的日志输出
  3. 在现有代码中集成日志调用

  是否需要我查看项目结构后再开始？(y/n)

> y

  🤖 正在扫描项目结构...
  发现以下文件：
  - main.py (入口)
  - api/routes.py (路由)
  - services/user_service.py (业务逻辑)

  我将创建一个统一的日志配置，然后在关键位置添加日志调用。
  继续？(y/n)

> y

  🤖 好的，开始执行...
  [创建 logger.py]
  [修改 main.py - 添加日志初始化]
  [修改 api/routes.py - 添加请求日志]

  ✅ 日志系统已集成完毕。是否需要运行测试验证？

/help          - 显示帮助信息
/exit, /quit   - 退出交互模式
/clear         - 清空当前对话历史
/save <file>   - 保存当前对话到文件
/load <file>   - 从文件加载对话历史
/model <name>  - 切换模型
/config        - 显示当前配置
/retry         - 重试上一次请求
/shell <cmd>   - 执行 Shell 命令
/edit <file>   - 编辑指定文件
/undo          - 撤销上一次文件修改
/history       - 显示操作历史

# 在交互模式中，你可以直接让 AI 编辑文件

> 把 config.py 中的数据库连接字符串改为从环境变量读取

  🤖 好的，我将修改 config.py：

  --- config.py (修改前) ---
  DATABASE_URL = "postgresql://user:pass@localhost/mydb"

  --- config.py (修改后) ---
  import os
  DATABASE_URL = os.environ.get(
      "DATABASE_URL",
      "postgresql://user:pass@localhost/mydb"
  )

  确认修改？(y/n)

> y

  ✅ 文件已保存。

你的任务是什么类型？
    │
    ├── 一次性代码生成？
    │   └──→ 单任务模式
    │
    ├── 代码审查 / 解释？
    │   └──→ 单任务模式
    │
    ├── CI/CD 中的自动化？
    │   └──→ 单任务模式
    │
    ├── 编辑器集成？
    │   └──→ 单任务模式
    │
    ├── 需要多轮讨论？
    │   └──→ 交互模式
    │
    ├── 项目重构？
    │   └──→ 交互模式
    │
    ├── 学习新框架？
    │   └──→ 交互模式
    │
    └── 逐步构建功能？
        └──→ 交互模式

# 受限模式下，只有白名单中的命令可以执行
# 查看当前白名单
openclaw config show | grep allowed_commands

# 默认白名单通常包括：
# ls, cat, grep, find, python3, pip, git, echo, mkdir, cp, mv

# 示例：让 AI 执行命令

> 列出当前目录下的 Python 文件

  🤖 正在执行: find . -name "*.py" -type f

  结果：
  ./main.py
  ./src/utils.py
  ./src/config.py
  ./tests/test_main.py

> 运行测试

  🤖 正在执行: python3 -m pytest tests/ -v

  结果：
  ======================== test session starts =========================
  tests/test_main.py::test_hello PASSED                           [33%]
  tests/test_main.py::test_add PASSED                             [66%]
  tests/test_main.py::test_divide PASSED                          [100%]
  ======================== 3 passed in 0.12s =========================

  ✅ 所有测试通过！

# 在 config.yaml 中调整 Shell 设置

shell:
  # 模式: restricted 或 full
  mode: restricted

  # 自定义白名单
  allowed_commands:
    - ls
    - cat
    - grep
    - find
    - python3
    - pip
    - git
    - pytest
    - make
    - docker

  # 黑名单（优先级高于白名单）
  blocked_commands:
    - rm -rf /
    - sudo
    - mkfs
    - dd
    - shutdown

  # 命令超时
  timeout: 60

  # 工作目录
  working_dir: null  # null = 当前目录

# OpenClaw 支持管道操作（单任务模式）

# 将代码审查结果保存到文件
openclaw "审查 main.py" > review_report.txt

# 链式调用
openclaw "解释这个函数的作用" -f main.py | grep -i "return"

# 将 AI 生成的代码直接保存到文件
openclaw "写一个 Python 快速排序" | tee quicksort.py

# 在脚本中使用
#!/bin/bash
# ai_review.sh
for file in src/*.py; do
  echo "=== 审查 $file ===" >> review.md
  openclaw --quiet "审查这段代码" -f "$file" >> review.md
  echo "" >> review.md
done

# 在单任务模式中让 AI 执行命令
openclaw "查看当前目录结构，分析项目类型"

# 指定允许执行的命令
openclaw --allow "ls,cat,grep" "分析日志文件"

# 完全禁用 Shell
openclaw --no-shell "解释这段代码"

# 纯文本输出（默认）
openclaw "写一个快速排序"

# JSON 格式输出
openclaw --json "提取以下 JSON 中的用户邮箱列表: [{...}]"

# Markdown 格式输出
openclaw --format markdown "为这个 API 编写文档"

# 安静模式（只输出核心结果）
openclaw --quiet "生成一个 hello world"

# 重定向输出
openclaw "生成一个 Flask API 模板" > flask_api.py

# 追加模式
openclaw "为这个函数添加文档字符串" -f utils.py >> docs.md

# 使用 --output 选项直接保存
openclaw --output generated_code.py "写一个 Python Web 爬虫"

# 带时间戳的自动命名
openclaw --output "output_$(date +%Y%m%d_%H%M%S).py" "生成代码"

# 从管道接收输入
cat requirements.txt | openclaw "分析这些依赖，指出过时的包"

# 管道串联
openclaw --quiet "提取所有函数名" -f main.py | sort | uniq

# 与 grep 配合
openclaw "列出所有 API 端点" -f routes.py | grep -E "@app\.(get|post|put|delete)"

# 与 jq 配合（JSON 输出）
openclaw --json "分析 API 响应结构" | jq '.endpoints[].path'

# 只显示代码块
openclaw "写一个快速排序" | grep -A 100 '```python' | grep -B 100 '```'

# 只保存代码到文件（去掉解释文字）
openclaw --quiet "写一个快速排序" > quicksort.py

# 使用 --code-only 选项（如果支持）
openclaw --code-only "生成配置文件" > config.yaml

# 设置最大输出长度
openclaw --max-length 500 "详细解释这个算法"

# 在配置文件中设置
# config.yaml
output:
  max_length: 5000
  format: text
  show_thinking: false
  show_tool_calls: false

# 让 AI 读取并分析文件
openclaw -f main.py "分析这个文件的代码风格"

# 读取多个文件
openclaw -f requirements.txt -f setup.py "检查依赖配置是否完整"

# 读取目录下所有相关文件
openclaw -d ./src "分析代码架构"

# 让 AI 创建新文件
openclaw "创建一个 .gitignore 文件，包含 Python 项目的常见忽略规则"

# 输出重定向到文件
openclaw "生成一个 pytest 配置文件" > pytest.ini

> 把 main.py 中的 print 语句替换为 logging 调用

  🤖 我将修改 main.py 中的 print 语句：

  修改 1 (第 15 行):
  - print(f"Starting server on port {port}")
  + logger.info(f"Starting server on port {port}")

  修改 2 (第 28 行):
  - print(f"Error: {e}")
  + logger.error(f"Error: {e}")

  修改 3 (第 45 行):
  - print("Server stopped")
  + logger.info("Server stopped")

  共 3 处修改。确认？(y/n)

> y

  ✅ 文件已保存。3 处修改已应用。

# 安全配置
editor:
  # 修改前创建备份
  backup: true
  backup_dir: ~/.cache/openclaw/backups

  # 修改后自动验证
  auto_verify: true

  # 最大单次修改行数
  max_changes_per_file: 50

  # 禁止修改的文件模式
  protected_patterns:
    - "*.lock"
    - "node_modules/**"
    - ".git/**"

# 一次性生成完整项目
openclaw "搭建一个 Flask API 项目，包含以下要求：
1. 用户注册/登录功能（JWT 认证）
2. CRUD 操作的数据模型（User, Post）
3. SQLAlchemy + SQLite
4. 错误处理和日志
5. pytest 测试框架

将代码输出为多个文件，用分隔符标明文件名。"

# 保存输出
openclaw "搭建一个 Flask API..." > project.zip
# 注意：实际使用中可能需要手动整理文件

#!/bin/bash
# review.sh - 自动代码审查脚本

echo "# 代码审查报告" > review.md
echo "生成时间: $(date)" >> review.md
echo "" >> review.md

for file in $(find src -name "*.py"); do
  echo "## 审查: $file" >> review.md
  openclaw --quiet "审查这段代码，指出：
  1. 潜在 bug
  2. 性能问题
  3. 安全隐患
  4. 改进建议" -f "$file" >> review.md
  echo "" >> review.md
done

echo "审查完成，报告已保存到 review.md"

# 为整个项目生成文档
openclaw -d ./src "为这个 Python 项目生成完整的 API 文档，
  包括：模块说明、函数签名、参数说明、返回值、使用示例。
  输出为 Markdown 格式。" > docs/api.md

# 生成 README
openclaw "基于以下代码，生成一个专业的 README.md，
  包含：项目简介、安装指南、使用方法、API 文档链接、贡献指南。" \
  -d ./src > README.md

# 分析 Nginx 日志
openclaw "分析以下 Nginx 访问日志，统计：
1. 每个状态码的请求数量
2. Top 10 的 IP 地址
3. Top 10 的请求路径
4. 异常请求（4xx, 5xx）的时间分布

日志内容：
$(tail -n 1000 /var/log/nginx/access.log)"

# ❌ 不好的指令
openclaw "写个爬虫"

# ✅ 好的指令（结构化）
openclaw "任务：编写一个 Python 网络爬虫
目标：抓取 https://example.com 的文章列表
要求：
1. 使用 requests + BeautifulSoup
2. 支持分页（共 10 页）
3. 提取标题、链接、发布日期
4. 保存到 CSV 文件
5. 添加重试机制和错误处理
6. 遵守 robots.txt
输出：完整的 Python 脚本"

# 提供项目结构文件
echo "src/
├── main.py
├── api/
│   ├── __init__.py
│   └── routes.py
├── models/
│   ├── __init__.py
│   └── user.py
└── config.py" > structure.txt

openclaw "基于以下项目结构，为每个文件添加类型注解" \
  -f structure.txt -f src/main.py

#!/bin/bash
# batch_refactor.sh - 批量重构脚本

# 定义要执行的操作
OPERATION="将所有的 print 语句替换为 logging 调用"

# 遍历所有 Python 文件
find . -name "*.py" -not -path "./.venv/*" | while read file; do
  echo "处理: $file"

  # 检查是否包含 print
  if grep -q "print(" "$file"; then
    openclaw --quiet "$OPERATION" -f "$file" > "${file}.new"
    mv "${file}.new" "$file"
    echo "✅ 已更新: $file"
  else
    echo "⏭️ 跳过（无 print）: $file"
  fi
done

# Vim 集成：选中代码后按快捷键
# 在 .vimrc 中添加：
# nnoremap <leader>ai :.!openclaw --quiet "审查这段代码"<CR>

# VS Code 集成：通过 tasks.json
# {
#   "version": "2.0.0",
#   "tasks": [
#     {
#       "label": "OpenClaw Review",
#       "type": "shell",
#       "command": "openclaw --quiet '审查这段代码' -f ${file}",
#       "problemMatcher": []
#     }
#   ]
# }

# 1. 使用 --quiet 减少输出解析开销
openclaw --quiet "简单任务"

# 2. 减小上下文（只发送必要的文件）
openclaw -f relevant_file.py "任务"  # 而不是 -d ./whole_project

# 3. 使用更小的模型进行简单任务
openclaw --model gpt-4o-mini "简单代码补全"

# 4. 利用缓存
# 在 config.yaml 中启用缓存
# advanced:
#   cache:
#     enabled: true

# 问题：输出不完整，被截断

# 解决：增加最大输出长度
openclaw --max-length 20000 "长任务"

# 或在配置文件中设置
# output:
#   max_length: 50000

# 问题：AI 生成的文件修改无法应用

# 排查：
# 1. 检查文件是否被保护
# 2. 检查块大小是否合适
# 3. 查看日志文件
cat ~/.config/openclaw/openclaw.log | tail -50

# 解决：
# 在配置文件中调整
# editor:
#   block_size: 4096  # 增大块大小
#   strategy: precise  # 尝试精确模式

# 问题：AI 尝试执行的命令被拒绝

# 解决：
# 1. 查看被拒绝的命令
cat ~/.config/openclaw/openclaw.log | grep "command rejected"

# 2. 添加到白名单
# shell:
#   allowed_commands:
#     - ...
#     - your_command

# 问题：交互模式下响应延迟高

# 解决：
# 1. 切换到更快的模型
openclaw --model gpt-4o-mini

# 2. 减少上下文
clear  # 在交互模式中清空历史

# 3. 检查网络延迟
openclaw doctor