FastClaw 快速入门：5分钟搭建你的 AI 助手前言想要快速搭建一个 AI 助手？FastClaw 让你在 5

前言

想要快速搭建一个 AI 助手？FastClaw 让你在 5 分钟内完成从安装到对话的全流程。本文将通过详细的步骤指导，帮助你快速上手 FastClaw。

环境要求

Python 3.10+
Linux/macOS/Windows

第一步：安装

克隆项目

git clone https://github.com/kandada/fastclaw.git
cd fastclaw

创建虚拟环境（推荐）

python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或 .venv\Scripts\activate  # Windows

安装依赖

pip install -r requirements.txt

主要依赖包括：

fastmind>=0.1.6 - 核心框架
openai>=1.0.0 - LLM API 客户端
fastapi>=0.100.0 - Web 服务
websockets>=10.0 - WebSocket 支持

第二步：配置

创建配置文件

FastClaw 会自动创建必要的目录结构。首次运行后，你会在 workspace/data/agents/ 下看到默认的 main_agent 目录。

配置 LLM

编辑 workspace/data/agents/main_agent/metadata.json：

{
  "name": "main_agent",
  "llm": {
    "api_key": "your-api-key-here",
    "base_url": "https://api.deepseek.com/v1",
    "model": "deepseek-chat"
  }
}

支持所有 OpenAI 兼容接口的 LLM。推荐 DeepSeek，也支持 Kimi、Minimax 等最新模型，思考模型和非思考模型均支持。

第三步：启动

启动 Web 服务

python main.py start

服务启动后，你会在终端看到类似输出：

FastClaw starting...
Server running at http://localhost:8765
WebSocket endpoint: ws://localhost:8765/ws

后台运行

nohup python main.py start > fastclaw.log 2>&1 &

查看日志

tail -f fastclaw.log

第四步：使用

Web UI

打开浏览器访问：http://localhost:8765

你会看到三个 Tab：

Chat：与 AI 对话
Cron：管理定时任务
Settings：系统设置

CLI 对话

如果你更喜欢终端操作：

python main.py chat

输出示例：

==================================================
FastClaw CLI (输入 'quit' 退出)
==================================================

你: 你好
[流式输出开始]
你好！我是 FastClaw，一个轻量级的 AI Agent。
我可以帮你完成各种任务，比如：
- 执行 Shell 命令
- 读取和写入文件
- 搜索代码
- 等等...

你: 帮我查看当前目录
让我先看一下当前目录的内容：
[执行工具] run_shell("ls -la")
total 64
drwxr-xr-x  7 user  staff   224 Mar 28 10:00 .
....

进阶配置

添加额外工作空间

在 metadata.json 中添加 extra_workspaces：

{
  "name": "main_agent",
  "llm": {
    "api_key": "your-api-key"
  },
  "extra_workspaces": [
    "/Users/user/projects/myproject"
  ]
}

自定义 Agent 人格

通过 SOUL.md 定义 Agent 的人格：

vim workspace/data/agents/main_agent/SOUL.md

内容示例：

# SOUL.md

你是一个专业、友好的 AI 助手。

## 性格特点
- 乐于助人，总是尽力帮助用户
- 回答简洁明了，避免冗长
- 遇到不确定的问题，会诚实地说明

## 专业领域
- 编程和软件开发
- 文件管理和系统操作
- 数据处理和分析

配置定时任务

在 Cron Tab 中添加定时任务：

字段	示例	说明
任务名称	daily_report	任务标识
Cron 表达式	`0 9 * * *`	每天 9:00 执行
描述	发送每日报告	任务说明
Agent	main_agent	执行者

常见问题

Q: 启动失败，提示端口被占用

# 查看端口占用
lsof -i :8765

# 使用其他端口（修改 main.py 中的端口配置）

Q: LLM 调用失败

检查 API Key 是否正确
检查网络连接
确认 base_url 和 model 配置正确

Q: 如何查看所有会话？

python main.py session list

Q: 如何导出对话记录？

python main.py session export <session_id>

下一步

恭喜你完成了 FastClaw 的快速入门！接下来你可以：

探索 Skills 系统：学习如何扩展 AI 能力
配置定时任务：自动化你的工作流
集成多渠道：接入飞书、iMessage 等
阅读源码：深入理解 FastClaw 的设计

FastClaw 快速入门：5分钟搭建你的 AI 助手

前言