LingClaw

# LingClaw

<p align="center">
  <img src="static/branding/logo-wordmark.png" alt="LingClaw" width="320">
</p>

<p align="center">
  <strong>本地运行、Rust 构建的个人 AI Agent 工作台。</strong><br>
  连接你选择的模型、工具、Skills 与会话，把推理、执行和协作收进一个可控的工作循环。
</p>

<p align="center">
  <a href="README.md">简体中文</a> · <a href="README.en.md">English</a>
</p>

<p align="center">
  <img alt="Rust 2024" src="https://img.shields.io/badge/Rust-2024-2F3138?style=flat-square&logo=rust">
  <img alt="Windows and Linux" src="https://img.shields.io/badge/Windows%20%7C%20Linux-supported-6554D9?style=flat-square">
  <img alt="MIT License" src="https://img.shields.io/badge/license-MIT-438FD1?style=flat-square">
</p>

<p align="center">
  <img src="docs/assets/readme/zh/workspace.webp" alt="LingClaw 中文桌面工作台，展示会话导航、执行栈和工具检查器" width="100%">
</p>

LingClaw 把个人 AI 助手需要的模型路由、工具执行、会话工作区、记忆、MCP 和多代理协作放进一个本地服务。浏览器负责交互，Rust Runtime 负责状态、边界和持久化；你决定接入哪个 Provider、开放哪些工具，以及每个 Agent 使用什么模型。

> LingClaw 面向本机单用户使用，默认只监听 `127.0.0.1`。它不是自带身份认证的公网多用户服务。

## 快速开始

### 准备

- Git，以及能够访问 Rust、Node.js 和模型 Provider 的网络环境。
- Windows 使用 PowerShell 5.1 或更高版本；Linux 使用 Bash。
- 安装脚本会检查 Rust、Rust 原生链接器和 Node.js `>= 20.19.0`。Windows 的 MSVC 工具链缺少 C++ Build Tools 时，安装器会在构建前说明原因并询问是否通过 `winget` 安装；如果无法准备 Node.js，会在仓库包含可用 `static/` 时使用预构建前端。

### Windows

```powershell
git clone https://github.com/Linkq123/LingClaw.git
cd LingClaw
powershell -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1
```

### Linux

```bash
git clone https://github.com/Linkq123/LingClaw.git
cd LingClaw
bash scripts/install-linux.sh
```

安装脚本会构建 Rust 后端和最新前端，并部署内置 Skills 与 Sub-agents。快速开始时请选择 `Install`；如果希望以后直接输入 `lingclaw`，请同时接受 PATH 注册提示。

安装器运行在子进程中，当前终端不会继承它临时添加的 PATH。接受 PATH 注册后，可以重新打开终端并运行：

```bash
lingclaw
```

也可以不重开终端，直接从 Cargo 安装目录启动：

```powershell
$cargoHome = if ($env:CARGO_HOME) { $env:CARGO_HOME } else { Join-Path $HOME '.cargo' }
& (Join-Path $cargoHome 'bin\lingclaw.exe')
```

```bash
"${CARGO_HOME:-$HOME/.cargo}/bin/lingclaw"
```

首次启动会打开 Setup Wizard。普通对话开始前，需要完成两项显式配置：

1. 添加至少一个模型 Provider 和模型。
2. 为主 Agent 指定 `primary` 模型，或为当前 Session 使用 `/model` 选择已配置模型。

LingClaw 不会在缺少配置时静默调用内置默认模型。配置完成并启动服务后，访问 [http://127.0.0.1:18989](http://127.0.0.1:18989)。

也可以直接在项目目录打开终端工作台：

```bash
cd /path/to/project
lingclaw tui
```

`lingclaw tui [PATH]` 会复用已运行的本地服务，或自动启动 daemon。它按规范化目录恢复匹配的 Session；没有匹配项时会用当前文件夹名称预填一个目录工作空间，多项匹配时提供选择。首次没有可用模型时，TUI 会在终端内引导配置 Provider、模型和主 Agent，API Key 全程遮蔽。daemon 在退出 TUI 后继续运行。

输入区会区分不同的恢复路径：

- Provider 或 Model 尚未配置时，直接打开 Settings → Models。
- Agent `primary` 尚未配置时，直接打开 Settings → Agents。
- 当前 Session 的模型覆盖失效时，预填 `/model ` 让你重新选择。

这三种状态都会禁用普通发送，但仍允许状态、帮助和设置类命令，不会向未知模型发出请求。

常用服务命令：

```bash
lingclaw start
lingclaw stop
lingclaw restart
lingclaw status
lingclaw doctor
lingclaw update
lingclaw db status
lingclaw db backup
```

Session、Group、消息、Todos、Usage、工作目录绑定和 Sub-agent 快照存放在 `~/.lingclaw/lingclaw.db`。从旧版升级时，LingClaw 会在开始提供 HTTP 请求前严格校验并迁移原有 `sessions/`、`groups/` JSON；原文件会永久保留在 `~/.lingclaw/backups/sqlite-migration-*/`，不会继续双写。

安装细节、systemd、Docker 和反向代理说明见[部署指南](docs/deploy.md)。

## 你可以用 LingClaw 做什么

### 让 Agent 在受控循环中完成任务

LingClaw 使用 `Analyze → Act → Observe → Finish` 的 ReAct 状态机组织每轮工作。推理、工具调用、计划、Sub-agent 和 Orchestration 会聚合为可展开的执行栈；你可以查看过程、检查工具结果、在运行中追加指令或立即停止。

输入区默认直接执行；需要规划时，从始终可打开的 `+` 菜单进入，界面才显示“规划”标记。规划模式只做只读分析和必要提问，并生成带版本、步骤、风险与验收标准的结构化计划；批准后，Runtime 会在每个执行 cycle 注入精确 revision，并持续回写步骤进度与偏离原因。工作区证据变化时必须刷新计划或明确选择继续，批准动作不会伪造用户消息。Group 当前不开放规划模式。

### 连接不同模型与协议

同一套 Session 和工具体系支持：

- OpenAI-compatible Chat Completions
- OpenAI Responses
- Anthropic Messages
- Gemini
- Ollama

模型按 `provider/model` 路由。Primary、Fast、Sub-agent、Memory、Reflection 和 Context 可以分别配置。普通 Session 可直接在输入区搜索并原子切换模型与其允许的 Thinking Effort，选择会持久化；`/model` 与 `/think` 保持兼容。

### 用 Session 绑定项目，用 Group 组织协作

每个 Session 都有 LingClaw 私有的 `session_home`，用于提示、记忆、Skills、Agents 与策略；文件、Shell、Git、图片和 Plan evidence 则运行在可重绑的 `working_directory`。默认托管目录仍位于 `~/.lingclaw/<session-id>/workspace/`，也可以把 Session 绑定到已有项目目录。删除 Session 只删除数据库记录和私有 Home，绝不删除外部项目。

Group 可以把多个 Session 组织成群聊，支持广播、已选目标和 `@session-id` 精确提及；界面展示名称，协议始终使用稳定 ID。Group 默认关闭，需在 General 设置中显式开启；关闭和重新开启不会删除已有数据。

### 在内置工具、MCP 与 Skills 之间扩展能力

LingClaw 提供文件、命令、搜索、网络、Todos 和条件化图片查看等标准工具。MCP client 可以连接 stdio 与 Streamable HTTP server，并按 Session 授权 tools、resources 和 prompts。Skills 则通过 `SKILL.md` 为 Agent 注入可发现、可覆盖的领域工作流。

### 把任务委托给 Sub-agents

`task` 用于单个委托，`orchestrate` 用于带依赖关系的 DAG 编排。内置代理覆盖探索、研究、前端、后端、通用实现和审查；每个 Sub-agent 在独立的受控 loop 中运行，并继承明确的模型与工具边界。

### 保存记忆并处理视觉输入

Session 可以维护人工可读的 `MEMORY.md`、每日日志、可选 Structured Memory 和 Daily Reflection。配置 S3-compatible 存储且模型声明图片输入能力后，用户附件、MCP 图片和 `view_image` 结果可以进入下一次模型请求；原始工具 Base64 不会写入日志、WebSocket 或 SQLite。

## 产品界面

### 清晰的执行过程

Reasoning、Tool、Task Plan、Sub-agent 和 Orchestration 统一进入单个执行栈。完成后保留紧凑摘要，展开时可查看每一步；工具参数、结果和图片进入独立 Inspector，不挤压主对话。

### 面向协作的群聊

<p align="center">
  <img src="docs/assets/readme/zh/group.webp" alt="LingClaw 中文群聊界面，展示目标模式、成员状态和 Markdown 消息" width="860">
</p>

Group 上下文栏提供“全部 / 已

... (truncated)