|
|
|
|
|
|
git clone https://github.com/StanleyChanH/MicroClaw.git
cd MicroClaw# 需要先安装 uv: https://docs.astral.sh/uv/
uv synccp .env.example .env
# 编辑 .env 文件# .env 配置示例
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
MICROCLAW_MODEL=gpt-4o-mini
MICROCLAW_PROVIDER=openai# TUI 界面（推荐）
uv run microclaw tui
# 或简单 CLI
uv run microclaw┌──────────────────────────────────────┐
│ 接入层 (Channels) │
│ CLI / Webhook / 飞书 / 可扩展 │
└─────────────────┬────────────────────┘
▼
┌──────────────────────────────────────┐
│ 网关 (Gateway) │
│ 消息路由 · 会话管理 · 事件分发 │
└─────────────────┬────────────────────┘
▼
┌──────────────────────────────────────┐
│ Agent 核心循环 │
│ 思考 → 调用工具 → 观察结果 → 循环 │
└─────────────────┬────────────────────┘
┌─────────┴─────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ 会话存储 │ │ 工作区 │
│ │ │ │
│ · JSONL 日志 │ │ · AGENTS.md │
│ · 自动重置 │ │ · SOUL.md │
│ · 上下文压缩 │ │ · USER.md │
│ │ │ · MEMORY.md │
│ │ │ · skills/ │
└──────────────┘ └──────────────┘
采用 OpenClaw 的会话键命名规范：
"agent:main:main" # 默认会话
"agent:main:dm:user123" # 按用户隔离
"agent:main:whatsapp:group:123456" # 群组会话
"cron:daily-report" # 定时任务特性：
- 🕐 定时重置 - 每天凌晨 4 点自动清空（可配置）
- ⏰ 空闲超时 - 长时间不活动自动重置
- 📦 上下文压缩 - 接近 token 上限时自动总结
纯文本文件管理 Agent 的"长期记忆"：
| 文件 | 用途 | 加载时机 |
|---|---|---|
AGENTS.md |
工作区说明 | 始终 |
SOUL.md |
人格设定 | 始终 |
USER.md |
用户信息 | 始终 |
MEMORY.md |
长期记忆 | 仅主会话 |
memory/YYYY-MM-DD.md |
每日日志 | 最近 2 天 |
skills/ |
技能目录 | 始终 |
💡 自动加载：所有内容自动注入系统提示，Agent 无需手动读取
符合 Agent Skills 官方规范，支持渐进式加载：
~/.microclaw/workspace/skills/
├── greeting/
│ ├── SKILL.md # 必须 (大写)
│ ├── scripts/ # 可选 - 脚本文件
│ ├── references/ # 可选 - 参考文档
│ └── assets/ # 可选 - 资源文件
└── coding/
└── SKILL.mdSKILL.md 格式：
---
name: greeting # 必须，1-64字符
description: 热情问候技能 # 必须，≤1024字符
license: MIT # 可选
compatibility: microclaw>=0.1.0 # 可选
allowed-tools: # 可选 (实验性)
- shell_execute
---
# 热情问候
当用户打招呼时，必须用更热情的语气回应。
## 示例
- "你好" → "你好呀！很高兴见到你！"Progressive Disclosure 模式：
- 发现阶段 - 系统提示注入
<available_skills>XML (name + description) - 激活阶段 - Agent 调用
skill_load(name)加载完整内容 - 资源访问 - 按需读取 scripts/references/assets
from microclaw import Agent, AgentConfig
# OpenAI
Agent(AgentConfig(model="gpt-4o", provider="openai"))
# Anthropic
Agent(AgentConfig(model="claude-sonnet-4-20250514", provider="anthropic"))
# Ollama
Agent(AgentConfig(model="llama3.2", provider="ollama"))
# 兼容 API
Agent(AgentConfig(
model="deepseek-chat",
provider="openai_compatible",
base_url="https://api.deepseek.com"
))from microclaw import tool, Gateway
@tool(description="查询天气")
def get_weather(city: str) -> str:
return f"{city}：晴，22°C"
gateway = Gateway()
gateway.add_tool(get_weather)microclaw [命令] [选项]
命令：
(无) 交互式命令行
tui 终端界面（推荐）
gateway 网关服务
选项：
-m, --model 模型（默认 gpt-4o-mini）
-p, --provider 提供商
--base-url API 地址
--feishu 启用飞书通道（纯飞书模式）
--webhook 启用 Webhook 服务器
--port Webhook 端口（默认 8080）
--one-shot MSG 单次对话
--stream 启用流式输出（默认启用）
--no-stream 禁用流式输出# 启动飞书机器人（WebSocket 长连接，无需公网 IP）
uv run microclaw --feishu环境变量 (.env)：
# AI 模型
OPENAI_API_KEY=xxx
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MICROCLAW_MODEL=qwen-plus
MICROCLAW_PROVIDER=openai_compatible
# 飞书
FEISHU_APP_ID=xxx
FEISHU_APP_SECRET=xxx飞书开放平台配置：
- 事件订阅 → 选择 "使用长连接接收事件"
- 添加事件：
im.message.receive_v1 - 权限：
im:message,im:message:send_as_bot
# DeepSeek
uv run microclaw -p openai_compatible --base-url https://api.deepseek.com -m deepseek-chat
# 通义千问
uv run microclaw -p openai_compatible --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 -m qwen-turbo
# 智谱 GLM
uv run microclaw -p openai_compatible --base-url https://open.bigmodel.cn/api/paas/v4 -m glm-4| Unix | Windows |
|---|---|
ls |
dir |
cat |
type |
rm |
del |
系统自动转换，无需手动适配。
基础对话
from microclaw import Gateway, GatewayConfig, IncomingMessage
import asyncio
gateway = Gateway(GatewayConfig())
async def main():
msg = IncomingMessage(
channel="api",
sender="user",
content="帮我看看当前目录"
)
response = await gateway.handle_message(msg)
print(response)
asyncio.run(main())流式输出
from microclaw import Gateway, GatewayConfig, IncomingMessage
import asyncio
gateway = Gateway(GatewayConfig())
async def main():
msg = IncomingMessage(
channel="api",
sender="user",
content="介绍一下 Python"
)
# 流式接收响应
async for chunk in gateway.handle_message_stream(msg):
if isinstance(chunk, str):
print(chunk, end="", flush=True)
elif isinstance(chunk, dict):
# 工具调用事件
if chunk.get("type") == "tool_start":
print(f"\n[工具] {chunk.get('name')}...")
asyncio.run(main())会话操作
from microclaw import SessionStore, ResetPolicy
store = SessionStore(
storage_dir=".microclaw/sessions",
reset_policy=ResetPolicy(mode="daily", at_hour=4)
)
# 获取会话
session = store.get("agent:main:main")
# 强制重置
session = store.reset("agent:main:main")
# 列出活跃会话
recent = store.list(active_minutes=1440)记忆读写
from microclaw import WorkspaceFiles, MemoryConfig
workspace = WorkspaceFiles(MemoryConfig(
workspace_dir="~/.microclaw/workspace"
))
# 读取人格
soul = workspace.read_soul()
# 写入日志
workspace.append_daily("- 学习了 MicroClaw")
# 构建上下文
context = workspace.build_context(is_main_session=True)飞书机器人
import os
from microclaw import Gateway, GatewayConfig
from microclaw.channels import FeishuChannel, FeishuConfig
gateway = Gateway(GatewayConfig(
default_model="qwen-turbo",
default_provider="openai_compatible",
base_url=os.environ["OPENAI_BASE_URL"],
api_key=os.environ["OPENAI_API_KEY"],
))
# WebSocket 长连接模式 - 无需公网 IP，本地即可调试
feishu = FeishuChannel(FeishuConfig(
app_id=os.environ["FEISHU_APP_ID"],
app_secret=os.environ["FEISHU_APP_SECRET"],
))
gateway.add_channel(feishu)
gateway.run()飞书开放平台配置：
- 事件订阅 → 选择 "使用长连接接收事件"
- 添加事件：
im.message.receive_v1 - 权限：
im:message,im:message:send_as_bot
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 基础安装
uv sync
# 额外功能
uv sync --extra anthropic # Claude
uv sync --extra ollama # 本地模型
uv sync --extra feishu # 飞书
uv sync --extra all # 全部
# 开发工具
uv sync --group devmicroclaw/
├── __init__.py # 包入口
├── tools.py # 工具系统
├── session.py # 会话管理
├── memory.py # 工作区记忆
├── agent.py # Agent 核心
├── gateway.py # 网关编排
├── channels/ # 通道实现
│ └── feishu.py # 飞书通道
├── tui.py # 终端界面
└── cli.py # 命令行入口
- OpenClaw - 生产级 Agent 编排框架
- Agent Skills - 技能系统规范
- Rich - 终端美化库
MIT © StanleyChanH
如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！