<div align="center">
  <img src="asedclaw_logo.png" alt="asedclaw" width="520">
  <h1>asedclaw</h1>
  <p>面向个人与团队的轻量级 AI Agent CLI / Gateway。</p>
  <p>
    <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  </p>
</div>

## 简介

`asedclaw` 是一个以本地配置、命令行交互和多渠道接入为核心的 AI Agent 项目。

当前代码库已经实现：

- CLI 聊天模式与单次命令模式
- Gateway 常驻运行
- 多渠道消息接入与回发
- 内置技能加载与工作区模板同步
- 定时任务（Cron）和 Heartbeat 执行
- 多 Provider 路由与 OAuth 登录
- WhatsApp 本地 bridge 自动安装与构建

项目默认使用：

- 配置文件：`~/.asedclaw/config.json`
- 工作区：`~/.asedclaw/workspace`
- 运行时目录：`~/.asedclaw/{logs,media,cron,bridge,...}`

## 当前能力

### CLI 命令

`asedclaw` 当前暴露的主要命令：

```bash
asedclaw onboard
asedclaw onboard --overwrite
asedclaw onboard --no-overwrite
asedclaw agent
asedclaw gateway
asedclaw status
asedclaw channels status
asedclaw channels login
asedclaw provider login openai-codex
asedclaw provider login github-copilot
```

其中：

- `onboard`：初始化配置和工作区
- `agent`：直接与 Agent 对话，支持 `-m` 单次消息模式和交互模式
- `gateway`：启动常驻服务，接入渠道、Cron、Heartbeat
- `status`：输出当前配置、工作区、模型和 Provider 状态
- `channels status`：查看渠道启用状态
- `channels login`：初始化 WhatsApp bridge 并扫码登录

### 已实现渠道

代码中当前已集成这些渠道：

- Telegram
- WhatsApp
- Discord
- Feishu
- Mochat
- DingTalk
- Slack
- QQ
- Matrix
- Email
- ASED IM（SuperAgent IM）

注意：

- 除 `ased` 渠道外，其他渠道如果 `allowFrom` 为空，启动时会被视为“拒绝所有用户”并直接退出。
- 如果要公开接入，请显式设置 `["*"]`。

### 已实现 Provider

当前 Provider Registry 已包含：

- `custom`
- `azure_openai`
- `openrouter`
- `aihubmix`
- `siliconflow`
- `volcengine`
- `anthropic`
- `openai`
- `openai_codex`
- `github_copilot`
- `deepseek`
- `groq`
- `zhipu`
- `dashscope`
- `vllm`
- `gemini`
- `moonshot`
- `minimax`

其中：

- `openai_codex`、`github_copilot` 支持 OAuth 登录
- `custom` 用于任意 OpenAI 兼容接口
- `openrouter`、`aihubmix`、`siliconflow`、`volcengine` 属于网关型 Provider

### 工作区与模板

首次运行或启动时，`asedclaw` 会同步工作区模板，当前会自动创建或补齐：

- `AGENTS.md`
- `HEARTBEAT.md`
- `SOUL.md`
- `TOOLS.md`
- `USER.md`
- `memory/MEMORY.md`
- `memory/HISTORY.md`
- `skills/`

内置技能位于 [asedclaw/skills](asedclaw/asedclaw/skills)，运行时会被自动加载。

## 安装

### 从源码安装

```bash
git clone <your-repo-url>
cd asedclaw
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
```

### 使用 uv 安装

```bash
uv tool install .
```

如果后续要升级：

```bash
uv tool upgrade asedclaw
```

## 快速开始

### 1. 初始化

```bash
asedclaw onboard
```

执行后会创建：

- `~/.asedclaw/config.json`
- `~/.asedclaw/workspace`

### 2. 配置模型和 Provider

最小可用示例，使用 OpenRouter：

```json
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-3-7-sonnet-latest",
      "provider": "openrouter"
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-xxx"
    }
  }
}
```

如果你使用 OpenAI 兼容接口，可以改成 `custom`：

```json
{
  "agents": {
    "defaults": {
      "model": "MiniMax/MiniMax-M2.5",
      "provider": "custom"
    }
  },
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://your-openai-compatible-endpoint/v1"
    }
  }
}
```

### 3. 启动对话

单次消息：

```bash
asedclaw agent -m "你好，介绍一下你的能力"
```

交互模式：

```bash
asedclaw agent
```

带指定配置和工作区：

```bash
asedclaw agent -c ~/.asedclaw/config.json -w ~/.asedclaw/workspace
```

## Gateway 模式

启动常驻 Gateway：

```bash
asedclaw gateway
```

常用参数：

```bash
asedclaw gateway --port 18790
asedclaw gateway --config ~/.asedclaw/config.json
asedclaw gateway --workspace ~/.asedclaw/workspace
asedclaw gateway --verbose
```

Gateway 会负责：

- 启动启用的渠道
- 执行 Cron 任务
- 定期执行 Heartbeat
- 处理来自渠道和 CLI 的消息

## 渠道配置

配置项位于 `channels` 下。下面给出两个实际可用的最小示例。

### Telegram

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
```

### WhatsApp

```json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "bridgeUrl": "ws://localhost:3001",
      "allowFrom": ["+8613812345678"]
    }
  }
}
```

首次登录 WhatsApp：

```bash
asedclaw channels login
```

这会：

- 检查本地是否有 `npm`
- 从内置 bridge 或仓库根目录 bridge 复制文件
- 自动执行 `npm install`
- 自动执行 `npm run build`
- 启动 bridge 并等待扫码

查看当前渠道状态：

```bash
asedclaw channels status
```

## OAuth 登录

如果你使用 OAuth 型 Provider：

```bash
asedclaw provider login openai-codex
asedclaw provider login github-copilot
```

## 运行目录

`asedclaw` 的运行目录与配置文件位置相关，默认情况下会使用：

- `~/.asedclaw/config.json`
- `~/.asedclaw/workspace/`
- `~/.asedclaw/media/`
- `~/.asedclaw/cron/`
- `~/.asedclaw/logs/`
- `~/.asedclaw/bridge/`
- `~/.asedclaw/history/cli_history`

## 常用命令

```bash
asedclaw --version
asedclaw onboard
asedclaw onboard --overwrite
asedclaw onboard --no-overwrite
asedclaw agent
asedclaw agent -m "Hello"
asedclaw agent --no-markdown
asedclaw agent --logs
asedclaw gateway
asedclaw gateway --verbose
asedclaw status
asedclaw channels status
asedclaw channels login
asedclaw provider login openai-codex
asedclaw provider login github-copilot
```

## 开发与打包

当前项目打包元数据位于 [pyproject.toml](asedclaw/pyproject.toml)。

建议使用 Python 3.11 或 3.12。

本地开发常用流程：

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
```

如果你要发布包，建议先补齐：

- `python -m build`
- `python -m twine check dist/*`
- 干净虚拟环境安装 wheel 验证
- 至少一组基础 CLI / 配置 / 模板同步测试

## 许可证

MIT
