FastClaw 5分钟快速上手：从安装到第一个任务FastClaw 是一个轻量级的 Python AI Agent 助

FastClaw 是一个轻量级的 Python AI Agent 助手，基于 FastMind 框架开发。本文将带你从零开始，在 5 分钟内完成 FastClaw 的安装、配置和第一个任务。

前置要求

Python 3.10+
pip 包管理器
一个 OpenAI 兼容的 API Key（推荐 DeepSeek）

步骤 1：安装 FastClaw

方法一：从 GitHub 克隆（推荐）

# 克隆项目
git clone https://github.com/kandada/fastclaw.git
cd fastclaw

# 创建虚拟环境（可选但推荐）
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

方法二：快速安装脚本

# 一键安装脚本
curl -sSL https://raw.githubusercontent.com/kandada/fastclaw/main/install.sh | bash

步骤 2：配置 LLM API

FastClaw 支持所有 OpenAI 兼容的 API 接口。我们以 DeepSeek 为例：

获取 API Key

访问 DeepSeek 官网
注册账号并登录
在 API Keys 页面创建新的 API Key

配置 FastClaw

编辑配置文件：

vim workspace/data/agents/main_agent/metadata.json

将内容修改为：

{
  "llm": {
    "api_key": "你的 DeepSeek API Key",
    "base_url": "https://api.deepseek.com/v1",
    "model": "deepseek-chat"
  }
}

支持的其他 LLM

FastClaw 支持所有 OpenAI 兼容接口：

Kimi: base_url: "https://api.moonshot.cn/v1", model: "kimi-k2.5"
Minimax: base_url: "https://api.minimax.chat/v1", model: "MiniMax-M2.7"
OpenAI: base_url: "https://api.openai.com/v1", model: "gpt-5.4"
本地模型: 任何支持 OpenAI 格式的本地部署

步骤 3：启动 FastClaw

启动 Web 服务

# 启动服务（默认端口 8765）
python main.py start

# 或后台运行
nohup python main.py start > fastclaw.log 2>&1 &

验证服务

# 检查服务状态
curl http://localhost:8765/health

# 查看日志
tail -f fastclaw.log

服务启动后，访问 http://localhost:8765 打开 Web UI。

步骤 4：使用 Web UI

界面概览

FastClaw Web UI 包含三个主要标签页：

Chat: 交互式聊天界面
Cron: 定时任务管理
Settings: 系统设置

首次对话

打开 http://localhost:8765
在 Chat 页面输入框输入消息
按 Enter 发送，Shift+Enter 换行

示例对话：

你：你好，FastClaw！
FastClaw：你好！我是 FastClaw，你的 AI 助手。我可以帮你执行命令、管理文件、自动化任务。有什么可以帮你的吗？

你：查看当前目录的文件
FastClaw：执行 run_shell("ls -la")
（显示当前目录文件列表）

步骤 5：基础功能体验

1. 文件操作

你：查看 README.md 文件内容
FastClaw：执行 run_shell("cat README.md")

你：在当前目录创建 test.txt 文件
FastClaw：执行 run_shell("echo '测试内容' > test.txt")

2. 系统信息

你：查看系统内存使用情况
FastClaw：执行 run_shell("free -h")

你：查看磁盘空间
FastClaw：执行 run_shell("df -h")

3. 网络请求

你：获取当前时间
FastClaw：执行 run_shell("date")

你：查询天气（需要网络）
FastClaw：执行 run_shell("curl wttr.in/Beijing?format=3")

步骤 6：使用 Skills 系统

查看可用 Skills

你：有哪些可用的技能？
FastClaw：执行 run_skills("__list__")

使用内置 Skills

你：获取当前时间
FastClaw：执行 run_skills("current_time")

你：发送飞书消息
FastClaw：执行 run_skills("feishu", {"message": "测试消息"})

步骤 7：创建定时任务

通过 Web UI 创建

切换到 Cron 标签页
点击 "新建任务"
填写任务信息：
- 名称: 每日报告
- Cron 表达式: 0 9 * * *（每天 9 点）
- Agent: main_agent
- 命令: 生成今日工作报告
点击保存

通过配置文件创建

编辑 workspace/data/cron/tasks.json：

{
  "tasks": [
    {
      "name": "每日报告",
      "cron": "0 9 * * *",
      "agent": "main_agent",
      "session_id": "daily_report",
      "command": "生成今日工作报告并保存到文件",
      "enabled": true
    }
  ]
}

Cron 表达式示例

表达式	含义
`/5 * * *`	每 5 分钟
`0 * * * *`	每小时
`0 9 * * *`	每天 9 点
`0 9 * * 1-5`	工作日 9 点
`0 9,18 * * *`	每天 9 点和 18 点

步骤 8：高级功能探索

1. 会话管理

# 查看所有会话
python main.py session list

# 导出会话历史
python main.py session export default

2. 命令行交互

# 启动 CLI 交互
python main.py chat

# 新建会话
python main.py chat --new

# 指定会话
python main.py chat --session-id my_session

3. 技能开发

创建自定义技能：

# 创建技能目录
mkdir -p workspace/skills/user/my_skill

# 创建技能描述
cat > workspace/skills/user/my_skill/SKILL.md << EOF
# My Skill

## Description
我的自定义技能示例

## Parameters
- param1: 参数1说明
- param2: 参数2说明
EOF

# 创建技能实现
cat > workspace/skills/user/my_skill/main.py << EOF
async def execute(param1: str = "", param2: str = "") -> str:
    return f"Skill executed with params: {param1}, {param2}"
EOF

步骤 9：故障排除

常见问题

1. 服务启动失败

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

# 检查依赖
pip list | grep fastmind

# 查看详细日志
python main.py start --verbose

2. API 连接失败

检查 API Key 是否正确
检查网络连接
尝试其他 LLM 提供商

3. 权限问题

# 检查文件权限
ls -la workspace/

# 修复权限
chmod -R 755 workspace/

调试模式

# 启用调试日志
export FASTCLAW_LOG_LEVEL=DEBUG
python main.py start

步骤 10：生产环境部署

使用 systemd（Linux）

# 创建服务文件
sudo cat > /etc/systemd/system/fastclaw.service << EOF
[Unit]
Description=FastClaw AI Assistant
After=network.target

[Service]
Type=simple
User=fastclaw
WorkingDirectory=/opt/fastclaw
ExecStart=/opt/fastclaw/.venv/bin/python main.py start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable fastclaw
sudo systemctl start fastclaw

使用 Docker

FROM python:3.9-slim

WORKDIR /app
COPY . .

RUN pip install -r requirements.txt

EXPOSE 8765
CMD ["python", "main.py", "start"]

最佳实践

1. 安全配置

使用环境变量存储 API Key
限制可访问的目录
定期更新依赖

2. 性能优化

使用轻量级 LLM 模型
合理设置上下文长度
启用自动上下文卸载

3. 备份策略

# 备份配置和数据
tar -czf fastclaw_backup_$(date +%Y%m%d).tar.gz workspace/

下一步

学习资源

官方文档: 项目 README.md
代码示例: core/app.py 中的核心实现
社区支持: GitHub Issues 和 Discussions

进阶主题

自定义 Agent: 创建具有特定人格的 Agent
集成第三方服务: 连接数据库、消息队列等
性能监控: 添加监控和告警
集群部署: 多节点高可用部署

贡献指南

报告问题: GitHub Issues
提交 PR: 遵循代码规范
编写文档: 帮助改进文档
分享案例: 分享你的使用经验

总结

通过本教程，你已经完成了：

✅ FastClaw 的安装和配置
✅ LLM API 的设置
✅ 基础功能的使用
✅ 定时任务的创建
✅ 故障排除方法

FastClaw 的设计理念是"简单而强大"。它通过极简的配置和直观的界面，让 AI Agent 技术变得触手可及。无论你是开发者、运维工程师还是普通用户，都能快速上手并发挥其价值。

开始你的 AI Agent 之旅吧！

FastClaw 5分钟快速上手：从安装到第一个任务