User Guide

Learn how to use moltbot with practical examples and best practices.

Contents

Basics

Task management

Task management is the core of moltbot: create, edit, run, and remove tasks.

Create a task

# 使用命令行创建任务
moltbot task create --name "任务名称" --type "task_type"

# 使用配置文件创建
moltbot task create --config task.yaml

Inspect tasks

# 列出所有任务
moltbot task list

# 查看任务详情
moltbot task show "任务名称"

# 查看任务状态
moltbot task status "任务名称"

Run tasks

# 运行单个任务
moltbot task run "任务名称"

# 运行所有任务
moltbot task run --all

# 后台运行
moltbot task run "任务名称" --daemon

Logs

Use logs to understand what happened during execution.

# 查看实时日志
moltbot log tail

# 查看指定任务的日志
moltbot log show "任务名称"

# 查看最近的日志
moltbot log recent --lines 100

Configuration

Config file structure

moltbot uses YAML configuration. Example:

# 应用配置
app:
  name: "moltbot"
  version: "1.0.0"
  debug: false

# 全局设置
settings:
  language: "zh-CN"
  timezone: "Asia/Shanghai"
  log_level: "info"
  log_file: "~/.moltbot/logs/app.log"
  
# 任务配置
tasks:
  - name: "示例任务1"
    enabled: true
    schedule: "0 */6 * * *"
    action:
      type: "command"
      command: "echo 'Hello World'"
      
  - name: "示例任务2"
    enabled: true
    trigger:
      type: "file"
      path: "/watch/directory"
      events: ["create", "modify"]
    action:
      type: "script"
      script: "process.sh"

Common settings

KeyTypeDescriptionDefault
log_levelstring日志级别：debug, info, warn, errorinfo
max_concurrent_tasksnumber最大并发任务数10
task_timeoutnumber任务超时时间（秒）3600
retry_countnumber任务失败重试次数3

Advanced

Scheduling

Use Cron expressions for schedules:

task:
  name: "定时任务"
  schedule: "0 0 * * *"  # 每天午夜执行
  action:
    type: "backup"

Common examples:

  • "0 * * * *" - 每小时执行
  • "0 0 * * *" - 每天午夜执行
  • "0 0 * * 0" - 每周日午夜执行
  • "0 0 1 * *" - 每月1号午夜执行

File watching

Watch file changes and trigger tasks:

task:
  name: "文件监控任务"
  watch:
    path: "/path/to/watch"
    recursive: true
    events: ["create", "modify", "delete"]
  action:
    type: "process"
    command: "handle_file.sh"

Conditional execution

Run tasks only when conditions are met:

task:
  name: "条件任务"
  condition:
    type: "file_exists"
    path: "/path/to/file"
  action:
    type: "command"
    command: "process.sh"

Best Practices

1. Config management

  • Version control your configs
  • Use different configs per environment
  • Back up configs regularly
  • Document settings with comments

2. Task design

  • Split complex work into smaller tasks
  • Set reasonable timeouts
  • Add retries and error handling
  • Use meaningful task names

3. Logging

  • Choose the right log level
  • Clean up old logs
  • Use log rotation
  • Log key operations

4. Performance

  • Tune concurrency
  • Avoid resource contention
  • Cache to reduce repeated work
  • Monitor task duration

Tips

💡 Tip 1

Use --dry-run to validate a task without actually running it.

💡 Tip 2

Store secrets in environment variables instead of hardcoding them.

💡 Tip 3

Review task history regularly to spot issues early.

💡 Tip 4

Use templates to create similar tasks faster.

💡 Tip 5

Enable notifications for important tasks.

💡 Tip 6

Group related tasks for easier bulk management.