旅行青蛙 Travel Frog 🐸

English | 中文

中文

项目介绍

旅行青蛙是一个基于 OpenClaw 的放置类 Agent 游戏。你的青蛙会自主旅行、寄明信片、拍照片、写日记，就像经典的《旅行青蛙》游戏一样。

✨ 特性

🐸 自主旅行 — 青蛙会根据心情和时间自己决定出门旅行
📮 明信片系统 — 旅途中会寄明信片回来，带图片和文字
📸 拍照功能 — 可以让青蛙拍照分享当前状态
📔 日记系统 — 青蛙会写日记记录每天的经历
🎁 纪念品收集 — 旅行回来会带回当地纪念品
🗺️ 世界探索 — 青蛙会逐步解锁新地区，学习当地文化
🎨 AI 图片生成 — 明信片和照片由 AI 自动生成（推荐 OpenAI gpt-image-1.5）

📋 前置准备

开始之前，请准备好以下信息：

类型	说明	获取方式
Discord Bot Token 或 Telegram Bot Token	消息收发（必需）	Discord Developer Portal / BotFather
UserId	消息发送目标（必需）	Telegram: 通过 @userinfobot 获取
OpenAI API Key	AI 图片生成（可选，推荐）	OpenAI Platform
Gemini API Key	AI 图片生成（可选，替代方案）	Google AI Studio

🚀 快速开始

自动安装（推荐）

npx travel-frog@latest

安装器会引导你完成：

环境检查
Skill 安装
Workspace 创建
给青蛙起名
配置消息频道
设置图片生成
自动配置 OpenClaw

手动安装

如果你更喜欢手动配置：

1. 安装 skill

clawhub install travel-frog -workdir ~/.openclaw/workspace-frog

2. 复制模板文件

SOURCE_DIR=~/.openclaw/workspace-frog/skills/travel-frog/templates
DEST_DIR=~/.openclaw/workspace-frog

# 一次性复制所有文件和目录
cp "$SOURCE_DIR"/{AGENTS.md,SOUL.md,HEARTBEAT.md,TOOLS.md,IDENTITY.md} "$DEST_DIR/"
cp -r "$SOURCE_DIR/memory" "$DEST_DIR/"

3. 编辑 IDENTITY.md 给青蛙起名

nano ~/.openclaw/workspace-frog/IDENTITY.md

4. 配置 OpenClaw

编辑 ~/.openclaw/openclaw.json：

{
  "agents": {
    "list": [
      {
        "id": "frog",
        "workspace": "~/.openclaw/workspace-frog",
        "skills": ["travel-frog"]
      }
    ]
  },
  "bindings": [
    { "agentId": "frog", "match": {"channel": "discord", "accountId": "frog"}}
  ],
  "tools": {
    "profile": "full",
    "sessions": {"visibility": "all"}
  },
  "channels": {
    "discord": {
      "accounts": {
        "frog": {
          "token": "TOKEN"
        }
      }
    }
  }
}

5. 配置消息频道

编辑 ~/.openclaw/workspace-frog/TOOLS.md，填写你的频道信息：

## 消息发送

- `accountId`: `frog`
- `channel`: `discord`（或 `telegram`）
- `target`: `TARGET`（discord:UserId/telegram:UserId）

6. 配置图片生成（可选）

将全局安装的图片生成 skill 软链接到 workspace 中：

# 找到全局 skill 目录（二选一）
# macOS: /opt/homebrew/lib/node_modules/openclaw/skills/
# Linux: ~/.npm-global/lib/node_modules/openclaw/skills/

GLOBAL_SKILLS=/opt/homebrew/lib/node_modules/openclaw/skills
ln -s "$GLOBAL_SKILLS/openai-image-gen" ~/.openclaw/workspace-frog/skills/
ln -s "$GLOBAL_SKILLS/nano-banana-pro" ~/.openclaw/workspace-frog/skills/

配置 API key 到 ~/.openclaw/.env：

OPENAI_API_KEY=sk-**
GEMINI_API_KEY=sk-**

7. 启动 OpenClaw

openclaw gateway start

8. 配置定时任务

openclaw cron add \
  --every 15m \
  --name "Travel Frog Engine" \
  --timeout-seconds 300 \
  --agent "frog" \
  --no-deliver \
  --message "用 exec 运行 \`python3 skills/travel-frog/scripts/frog_engine.py tick\`, 如果输出包含\`\"events\": []\`, 直接返回 NO_REPLY。否则读取 HEARTBEAT.md 处理返回的事件。"

📖 使用方法

查看青蛙状态

在配置的频道中发送：

看看蛙
在干嘛
frog status

查看明信片收藏

明信片
看明信片
postcards

让青蛙拍照

拍照
拍张照
来张照片

召回青蛙

回来
召回
叫醒

🎮 游戏机制

时间系统

默认配置：1 游戏小时 = 1 现实小时
睡觉时间：23:00 - 08:00
心跳频率：15 分钟检查一次

旅行系统

青蛙会根据以下因素决定是否出门：

当前时间（早上起床后、白天）
最近旅行历史（避免重复去同一个地方）
朋友推荐
节日和季节

旅程包含多个阶段：

Transit — 交通阶段（新干线、渡轮等）
Explore — 游玩阶段（景点、美食、活动）

明信片系统

每次旅行至少寄一张明信片
明信片包含文字描述和 AI 生成的图片
明信片会归档到收藏中

照片系统

可以随时让青蛙拍照
根据当前状态生成场景（在家/旅行中/睡觉）
照片也会归档到收藏中

记忆系统

青蛙会维护多个记忆文件：

memory/YYYY-MM-DD.md — 每日日记
memory/world_knowledge.md — 世界认知（已解锁区域）
memory/friend_tips.md — 朋友推荐
MEMORY.md — 长期记忆（旅行统计、成长记录）

🛠️ 配置说明

skills/travel-frog/config.json

{
  "sleepTime": {
    "start": 23,    // 睡觉时间（小时）
    "end": 8        // 起床时间（小时）
  },
  "travel": {
    "timeMultiplier": 3600  // 时间倍率（3600 = 正式体验）
  },
  "rewards": {
    "cloversOnReturn": 3,   // 回家获得三叶草数量
    "initialClovers": 10    // 初始三叶草数量
  }
}

🐛 故障排查

青蛙不发消息

检查 TOOLS.md 中的频道配置是否正确
检查 OpenClaw gateway 是否运行：openclaw gateway status
查看日志：tail -f ~/.openclaw/workspace-frog/travel-frog-data/engine.log

图片生成失败

检查图片生成 skill 是否安装
检查 API key 是否配置
查看 TOOLS.md 中的图片生成配置

心跳不工作

执行 openclaw cron list | grep "Travel Frog Engine"
重启 gateway：openclaw gateway restart

📝 开发指南

项目结构

travel-frog/
├── skill/                  # ClawHub skill
│   ├── SKILL.md           # 引擎文档
│   ├── config.json        # 默认配置
│   ├── scripts/           # 核心引擎
│   └── templates/         # Workspace 模板
├── bin/                   # npm 安装器
└── examples/              # 示例配置

本地测试

# 测试引擎
cd ~/.openclaw/workspace-frog/skills/travel-frog
python3 scripts/frog_engine.py status

# 测试心跳
python3 scripts/frog_engine.py tick

# 测试旅行
python3 scripts/frog_engine.py depart --journey '{"title":"测试","totalHours":1,"phases":[...]}'

贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add amazing feature'
推送分支：git push origin feature/amazing-feature
提交 Pull Request

📄 许可证

MIT License - 详见 LICENSE

🙏 致谢

OpenClaw - AI Agent 框架
经典游戏《旅行青蛙》的灵感

English

Introduction

Travel Frog is an idle agent game built on OpenClaw. Your frog will autonomously travel, send postcards, take photos, and keep a diary, just like the classic "Travel Frog" game.

✨ Features

🐸 Autonomous Travel — Frog decides when to travel based on mood and time
📮 Postcard System — Sends postcards with AI-generated images during trips
📸 Photo Feature — Take photos of current activities
📔 Diary System — Keeps daily diary entries
🎁 Souvenir Collection — Brings back local souvenirs
🗺️ World Exploration — Gradually unlocks new regions and learns local culture
🎨 AI Image Generation — Postcards and photos generated by AI (recommended: OpenAI gpt-image-1.5)

📋 Prerequisites

Before you begin, have the following ready:

Item	Description	Where to get
Discord Bot Token or Telegram Bot Token	Message channel (required)	Discord Developer Portal / BotFather
UserId	Message target (required)	Telegram: via @userinfobot
OpenAI API Key	AI image generation (optional, recommended)	OpenAI Platform
Gemini API Key	AI image generation (optional, alternative)	Google AI Studio

🚀 Quick Start

Automatic Installation (Recommended)

npx travel-frog@latest

The installer will guide you through:

Environment check
Skill installation
Workspace creation
Naming your frog
Configuring message channels
Setting up image generation
Auto-configuring OpenClaw

Manual Installation

If you prefer manual setup:

1. Install skill

clawhub install travel-frog -workdir ~/.openclaw/workspace-frog

2. Copy template files

SOURCE_DIR=~/.openclaw/workspace-frog/skills/travel-frog/templates
DEST_DIR=~/.openclaw/workspace-frog

# Copy all files and directories at once
cp "$SOURCE_DIR"/{AGENTS.md,SOUL.md,HEARTBEAT.md,TOOLS.md,IDENTITY.md} "$DEST_DIR/"
cp -r "$SOURCE_DIR/memory" "$DEST_DIR/"

3. Edit IDENTITY.md to name your frog

nano ~/.openclaw/workspace-frog/IDENTITY.md

4. Configure OpenClaw

Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "frog",
        "workspace": "~/.openclaw/workspace-frog",
        "skills": ["travel-frog"]
      }
    ]
  },
  "bindings": [
    { "agentId": "frog", "match": {"channel": "discord", "accountId": "frog"}}
  ],
  "tools": {
    "profile": "full",
    "sessions": {"visibility": "all"}
  },
  "channels": {
    "discord": {
      "accounts": {
        "frog": {
          "token": "TOKEN"
        }
      }
    }
  }
}

5. Configure message channel

Edit ~/.openclaw/workspace-frog/TOOLS.md with your channel info:

## Message Sending

- `accountId`: `frog`
- `channel`: `discord` (or `telegram`)
- `target`: `TARGET` (discord:UserId / telegram:UserId)

6. Configure image generation (optional)

Symlink image generation skills from the global installation into your workspace:

# Find your global skill directory (pick one)
# macOS: /opt/homebrew/lib/node_modules/openclaw/skills/
# Linux: ~/.npm-global/lib/node_modules/openclaw/skills/

GLOBAL_SKILLS=/opt/homebrew/lib/node_modules/openclaw/skills
ln -s "$GLOBAL_SKILLS/openai-image-gen" ~/.openclaw/workspace-frog/skills/
ln -s "$GLOBAL_SKILLS/nano-banana-pro" ~/.openclaw/workspace-frog/skills/

Configure API key in ~/.openclaw/.env:

OPENAI_API_KEY=sk-**
GEMINI_API_KEY=sk-**

7. Start OpenClaw

openclaw gateway start

8. Configure cron job

openclaw cron add \
  --every 15m \
  --name "Travel Frog Engine" \
  --timeout-seconds 300 \
  --agent "frog" \
  --no-deliver \
  --message "Run \`python3 skills/travel-frog/scripts/frog_engine.py tick\` via exec. If output contains \`\"events\": []\`, return NO_REPLY. Otherwise read HEARTBEAT.md and handle the returned events."

📖 Usage

Check frog status

Send in your configured channel:

看看蛙 (Chinese)
在干嘛 (Chinese)
frog status

View postcard collection

明信片 (Chinese)
postcards

Take a photo

拍照 (Chinese)
take a photo

Call frog home

回来 (Chinese)
come home

Recommend places

You should visit Hokkaido for lavender fields
I recommend Kyoto

The frog will remember your recommendations and may visit later.

🎮 Game Mechanics

Time System

Default: 1 game hour = 1 real hour
Sleep time: 23:00 - 08:00
Heartbeat frequency: Check every 15 minutes

Travel System

Frog decides to travel based on:

Current time (after waking up, daytime)
Recent travel history (avoids repeating same places)
Friend recommendations
Holidays and seasons

Journeys include multiple phases:

Transit — Transportation (bullet train, ferry, etc.)
Explore — Sightseeing (attractions, food, activities)

Postcard System

At least one postcard per trip
Postcards include text and AI-generated images
Postcards are archived in collection

Photo System

Take photos anytime
Generates scenes based on current state (home/traveling/sleeping)
Photos are also archived

Memory System

Frog maintains multiple memory files:

memory/YYYY-MM-DD.md — Daily diary
memory/world_knowledge.md — World knowledge (unlocked regions)
memory/friend_tips.md — Friend recommendations
MEMORY.md — Long-term memory (travel stats, growth records)

🛠️ Configuration

skills/travel-frog/config.json

{
  "sleepTime": {
    "start": 23,    // Sleep time (hour)
    "end": 8        // Wake time (hour)
  },
  "travel": {
    "timeMultiplier": 3600  // Time multiplier (3600 = real-time)
  },
  "rewards": {
    "cloversOnReturn": 3,   // Clovers earned on return
    "initialClovers": 10    // Initial clovers
  }
}

🐛 Troubleshooting

Frog not sending messages

Check channel config in TOOLS.md
Check OpenClaw gateway: openclaw gateway status
View logs: tail -f ~/.openclaw/workspace-frog/travel-frog-data/engine.log

Image generation fails

Check if image generation skill is installed
Check if API key is configured
Review image generation config in TOOLS.md

Heartbeat not working

Run openclaw cron list | grep "Travel Frog Engine"
Restart gateway: openclaw gateway restart

📝 Development

Project Structure

travel-frog/
├── skill/                  # ClawHub skill
│   ├── SKILL.md           # Engine documentation
│   ├── config.json        # Default config
│   ├── scripts/           # Core engine
│   └── templates/         # Workspace templates
├── bin/                   # npm installer
└── examples/              # Example configs

Local Testing

# Test engine
cd ~/.openclaw/workspace-frog/skills/travel-frog
python3 scripts/frog_engine.py status

# Test heartbeat
python3 scripts/frog_engine.py tick

# Test travel
python3 scripts/frog_engine.py depart --journey '{"title":"Test","totalHours":1,"phases":[...]}'

Contributing

Issues and Pull Requests are welcome!

Fork this repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push branch: git push origin feature/amazing-feature
Submit Pull Request

📄 License

MIT License - see LICENSE

🙏 Acknowledgments

OpenClaw - AI Agent Framework
Classic "Travel Frog" game for inspiration

Star ⭐ this repo if you like it!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
bin		bin
docs		docs
skill		skill
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

旅行青蛙 Travel Frog 🐸

中文

项目介绍

✨ 特性

📋 前置准备

🚀 快速开始

自动安装（推荐）

手动安装

📖 使用方法

查看青蛙状态

查看明信片收藏

让青蛙拍照

召回青蛙

推荐地方

🎮 游戏机制

时间系统

旅行系统

明信片系统

照片系统

记忆系统

🛠️ 配置说明

skills/travel-frog/config.json

🐛 故障排查

青蛙不发消息

图片生成失败

心跳不工作

📝 开发指南

项目结构

本地测试

贡献指南

📄 许可证

🙏 致谢

English

Introduction

✨ Features

📋 Prerequisites

🚀 Quick Start

Automatic Installation (Recommended)

Manual Installation

📖 Usage

Check frog status

View postcard collection

Take a photo

Call frog home

Recommend places

🎮 Game Mechanics

Time System

Travel System

Postcard System

Photo System

Memory System

🛠️ Configuration

skills/travel-frog/config.json

🐛 Troubleshooting

Frog not sending messages

Image generation fails

Heartbeat not working

📝 Development

Project Structure

Local Testing

Contributing

📄 License

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages