安装 tesseract 中文包，用于后续可能的 OCR 需求（可选）

<div align="center">
  <picture>
    <img alt="MobiClaw" src="assets/logo.jpg" width=10%>
  </picture>
</div>

<h3 align="center">
MobiClaw: A Lightweight OpenClaw Alternative with Seamless Mobile Manipulation
</h3>

---

MobiClaw 是轻量化的openClaw替代，能够支持网页搜索，文档生成，论文查找，定时任务，飞书机器人，skill注入，多智能体编排等核心功能，同时可以和 [MobiAgent](https://github.com/IPADS-SAI/MobiAgent) 对接，获取更强的手机控制与交互能力，实现端侧设备任务下发 - 控制 - 消息获取的端到端闭环。

当前主链路已经扩展为“**Router + Planner + Skill Selector + Executor**”的多智能体编排模型：

- **编排入口**：`app.py` + `mobiclaw/workflows.py`
- **编排核心**：`mobiclaw/orchestrator/`（execution / routing / skills / runner）
- **智能体**：`mobiclaw/agents/`（Steward / Worker / Router / Planner / Skill Selector / User / etc.）
- **工具层**：`mobiclaw/tools/`（mobi / web / shell / file / papers / office / etc.）
- **手机网关**：`mobiagent_server/server.py`（collect / action / jobs）
- **任务网关**：`mobiclaw/gateway_server/`（统一任务入口、异步任务、文件下载、飞书接入）
- **定时任务**：`mobiclaw/dailytasks/runner.py`
- **Skill 库**：`mobiclaw/skills/*/SKILL.md`

---

## 演示视频

<div align="center">
  <video src="https://github.com/user-attachments/assets/566821b0-5771-4907-b04e-8005094b0758"/>
</div>

---

## 文档导航

- 架构总览：`docs/MobiClaw-简化架构图.md`
- 架构详解：`docs/MobiClaw-项目架构说明.md`
- 详细分层图：`docs/MobiClaw-详细架构图.md`
- 详细项目拆解：`docs/MobiClaw-详细项目分析与拆解.md`
- 改进路线图：`docs/MobiClaw-改进路线图.md`
- 子模块文档：
  - `docs/模块-mobiclaw-core.md`
  - `docs/模块-tools.md`
  - `docs/模块-dailytasks.md`
  - `docs/模块-gateway.md`

---

## 当前运行模式概览

`python app.py` 统一从 `mobiclaw/workflows.py` 进入，按参数分为 3 种模式：

- **`--interactive`**：交互模式，终端多轮对话
- **`--daily --daily-trigger <trigger>`**：每日任务模式，也可通过--agent-task通过自然语言下发定时任务
- **`--agent-task "..."(推荐) `**：多智能体任务模式，会选择一个或者多个合适的智能体完成任务


---

## 从 0 到运行（推荐路径）

### 0) 基于Claude code + MobiClaw Skill 自动安装

如果你希望让Claude Code自动完成项目的环境配置与安装，可以在项目根目录启动 `claude`，然后输入 `/setup`，Claude Code会：

- 检查本地环境
- 安装项目依赖
- 交互式完成选项配置（如选择模型，接入飞书，配置可选项等）
- 在后台启动gateway server

在此过程中，你可以随时通过自然语言告诉Claude Code你希望它做什么，或让Claude Code解答你的问题。

若你不想使用Claude Code，或者希望自主控制项目的安装过程，你也可以按照下面的步骤手动安装项目：

### 1) 拉取代码与子模块

```bash
git clone <repo-url>
cd MobiClaw
git submodule update --init --recursive
```

### 2) 安装 Python 依赖

```bash
uv sync

# 安装 tesseract 中文包，用于后续可能的 OCR 需求（可选）
sudo apt-get update
sudo apt-get install -y tesseract-ocr-chi-sim
```

项目要求 Python 3.12+。

### 3) 配置环境变量

```bash
cp .env-example .env
```

然后至少补齐以下变量：

```bash
# LLM（必需）
export OPENROUTER_API_KEY='...'
# 或者：export OPENAI_API_KEY='...'

# Brave Search（联网搜索，需要代理）
export BRAVE_API_KEY='...'
```

常用补充项：

```bash
export OPENROUTER_MODEL='google/gemini-3-flash-preview'
export OPENROUTER_BASE_URL='https://openrouter.ai/api/v1'
```

`app.py` 与 `mobiclaw/gateway_server/` 启动时都会自动读取根目录 `.env`，仅在环境变量尚未存在时补齐。


### 4) 本地运行 MobiClaw

#### 4.1 交互模式

```bash
python app.py --interactive
```

输入 `exit` / `quit` / `退出` 可结束。

#### 4.2 Agent Task 模式

通过`--mode`指定具体的Agent：
```bash
python app.py --agent-task "从 arXiv 搜索今天的 Agent 论文并总结" --mode worker
```

#### 4.2.1 配置驱动自定义 Agent

当前支持通过配置文件自动注册自定义 Agent，并默认参与 Router/Planner 的候选集合。

- 配置文件路径：`mobiclaw/configs/custom_agent.json`
- 可选覆盖：环境变量 `MOBICLAW_CUSTOM_AGENT_CONFIG_PATH`
- 加载时机：进程启动加载一次
- 校验策略：`tools` 严格校验；若包含未知工具名，该 Agent 会被跳过并记录 warning

配置项说明：

- 必填字段：
- `agent_name`：Agent 名称（路由标识，内部会标准化为小写）
- `role`：该 Agent 的职责描述（供 Router 能力画像使用）
- `system_prompt`：该 Agent 的系统提示词
- 可选字段：
- `tools`：工具名列表（必须来自系统已注册工具名）
- `strengths`：能力优势列表
- `typical_tasks`：典型任务列表
- `boundaries`：能力边界列表
- `model_name`：该 Agent 专用模型（不填则沿用默认模型）
- `temperature`：该 Agent 温度参数
- `max_iters`：该 Agent 最大迭代轮数（1-50）

示例：

```json
{
  "agents": [
    {
      "agent_name": "research_assistant",
      "role": "负责论文与网页信息的深度检索和结构化总结",
      "system_prompt": "你是 MobiClaw 的 Research Assistant。你只处理检索、阅读、对比与总结类任务。",
      "tools": [
        "brave_search",
        "fetch_url_readable_text",
        "arxiv_search",
        "download_file",
        "extract_pdf_text"
      ],
      "strengths": ["跨来源信息检索与交叉验证"],
      "typical_tasks": ["检索并总结某个主题的最新论文"],
      "boundaries": ["不执行手机 GUI 操作"],
      "temperature": 0.2,
      "max_iters": 12
    }
  ]
}
```

使用方式：

- 自动路由：提交普通任务即可，Router 会把它作为候选 Agent
- 显式指定：可通过 `agent_hint` / `--agent-hint` 直接指定自定义 Agent

#### 4.2.2 Skill 自动选择

- 发现方式：扫描 `mobiclaw/skills/*/SKILL.md`
- 召回方式：规则召回 + 可选 LLM 重排
- 注入方式：把 skill 摘要注入目标 Agent 的 prompt 上下文
- 手动覆盖：支持 `--skill-hint`
- 可观测性：结果中的 `routing_trace.skills.records` 会记录候选、来源、原因和最终选择
- 当前 `routing_trace` 还会记录 `planner_allowed_agents` 等规划约束信息，方便定位路由与规划偏差

#### 4.2.3 `--agent-task` 常见示例

##### 智能路由多智能体模式（Router + Planner + Executor）

当前 `app.py --agent-task` 与 `gateway /api/v1/task` 默认都走统一编排：
- Router Agent：根据任务语义选择目标 Agent（LLM 语义路由 + 规则兜底）
- Planner Agent：复合任务自动拆分为阶段子任务（串并行混合）
- Executor：将子任务分发给 `Steward` / `Worker` / 其他Agent 执行并聚合结果
- Skill Selector：为每个子任务自动选择最合适的 Skill（规则召回 + LLM 重排，可为空）

联网搜索默认采用 Brave Search：先检索候选来源链接与摘要，再按需抓取网页正文。
实现见 [mobiclaw/workflows.py](mobiclaw/workflows.py) 与 [mobiclaw/orchestrator/](mobiclaw/orchestrator/)。

```bash
# 默认多智能体路由
python app.py --agent-task "帮我查看今天美伊战争的情况总结，并且生成

... (truncated)