Fastclaw

---

在网页上与 Agent 聊天，或将它们连接到 API 和 IM 渠道

Agent — 多个 Agent 并列运行，每个都有自己的模型、记忆和技能	自定义 — 在浏览器中编辑 SOUL.md、IDENTITY、记忆和心跳
渠道 — Telegram、Discord、Slack、WhatsApp、LINE、iMessage、WeChat、Feishu、WeCom	计划任务 — Agent 自主运行的 cron 和间隔任务

回复支持丰富的 Markdown 和代码 — 代码审查 Agent 发现 SQL 注入和竞争条件

FastClaw 是什么？

FastClaw 是一个 Agent 工厂 — 用于创建、管理和运行 AI Agent。每个 Agent 都有自己的个性（SOUL.md）、记忆、技能和工具。FastClaw 负责处理大模型通信、工具执行、沙箱隔离和会话管理。

# Install (drops the binary into ~/.local/bin and adds it to PATH)
curl -fsSL https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.sh | bash

Windows：

powershell -ExecutionPolicy Bypass -Command "iex(New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.ps1')"

快速开始

1. 首次运行

fastclaw
# Opens setup wizard → configure LLM provider → creates default agent.
# Foreground mode; ^C to stop. Use `fastclaw daemon start` to run in
# the background, or `fastclaw daemon install` to register a
# launchd / systemd service.

2. 控制面板

打开 http://localhost:18953，使用管理员令牌登录。

• Agent — 创建和管理 Agent，每个 Agent 都有自己的个性和模型
• 技能 — 从 ClawHub 或 GitHub 安装共享技能
• 模型 — 配置大模型提供商（OpenAI、Anthropic、Ollama、OpenRouter 等）
• API 密钥 — 签发程序化凭证（admin / user / agent 级别）
• 设置 — 常规（主题）、账户（个人资料 + 密码）、运行时（沙箱配置；仅管理员可用）

非管理员用户默认可访问范围受限的模型、API 密钥和 设置（常规 + 账户）。他们会看到标记为 Inherited 的管理员共享 资源，并可在其上叠加自己的私有配置 — 与 Agent 运行时使用的继承 模式相同。

3. Agent 管理

点击 Agent 进入其管理面板：

• 聊天 — 与 Agent 对话（调试/测试）
• 文件 — 编辑 SOUL.md、IDENTITY.md、MEMORY.md 等
• 技能 — Agent 私有技能
• 模型 — Agent 专属的提供商 + 模型覆盖项（按名称覆盖同名的系统条目；Agent 范围的 agents.defaults.model 会覆盖系统默认值）
• 渠道 — 连接 IM 机器人（Telegram、Discord、Slack），让终端用户可以在自己选择的平台上与 Agent 聊天
• 计划任务 — 检查和管理 Agent 通过 create_cron_job 创建的 cron 任务（“每天 9 点提醒我”“5 分钟后叫我”）；可在界面中暂停/删除
• 会话 — 对话历史

共享。 每个 Agent 的编辑对话框中都有一个 Public access 开关 （默认关闭）。开启后，任何拥有聊天 URL /agents/{id}/chat/ 的人都可以 使用自己的账户与 Agent 聊天；会话/记忆/USER.md 按聊天者隔离，而 SOUL / IDENTITY / 技能则从所有者的记录中共享。关闭后，只有所有者（或 super_admin） 可以访问。

架构

~/.fastclaw/
  fastclaw.db                # SQLite default — users, agents, sessions,
                             # apikeys, configs, agent_files all live here
  skills/                    # Shared skills (bundled + installed)
  agents/
    <agentId>/agent/skills/        # Agent-private skills (filesystem only)

除磁盘上的技能文件夹外，数据库是所有内容的事实来源。默认使用 SQLite；在多 Pod 部署中，将 FASTCLAW_STORAGE_DSN 指向 Postgres。

不存在 fastclaw.json。 引导设置（端口、绑定地址、存储 DSN、沙箱后端）来自 FASTCLAW_* 环境变量；所有面向用户的配置（提供商、渠道、设置、默认值）都存储在 configs 表中，并通过仪表板或 fastclaw agents config 编辑。

FastClaw 存储的内容

数据	所属对象	存储位置
Agent 记录、SOUL.md / IDENTITY.md / MEMORY.md / agent.json	Agent	数据库（agent_files 表）
会话（聊天历史）	Agent × 用户	数据库（sessions 表）
API 密钥、用户、作用域配置（提供商/渠道/设置）	平台	数据库
技能	Agent / 全局	文件系统（skills/、agents/<id>/agent/skills/）
用户账户、计费	应用程序	你的应用（ChatClaw 等）
输出文件	应用程序	你的应用 / S3

功能

大模型提供商

• OpenAI、Anthropic、Ollama、OpenRouter、Groq、DeepSeek、Mistral，以及任何兼容 OpenAI 的 API
• 每个 Agent 可单独覆盖提供商和模型（按名称，Agent 作用域优先于系统作用域）
• 支持提示词缓存（保留 RawAssistant）

渠道

• 为每个 Agent 绑定 Telegram / Discord / Slack 机器人 — 终端用户可在对应平台与 Agent 聊天
• 保存前验证令牌（Telegram getMe、Discord /users/@me、Slack auth.test）
• 会话按渠道和 chatID 隔离，因此用户的 Telegram 线程和 Discord 线程互不影响

工具与沙箱

• 内置工具：exec、read_file、write_file、list_dir、web_fetch、web_search、memory_search
• E2B 云沙箱或 Docker 沙箱 — 自动同步技能和工作区；执行后同步（每次工具调用后，沙箱侧文件都会镜像回持久存储）
• 沙箱在托管部署中是边界，在可自托管安装中是工具：设置 FASTCLAW_DEPLOY=hosted 后，所有 exec/file 调用都被限制在沙箱内；在可自托管安装中，默认使用主机 Shell，模型可通过每次调用时使用 exec(sandbox:true) 选择沙箱。设置 FASTCLAW_SANDBOX_ENFORCE=1，即可在可自托管安装中启用托管式锁定（当 Agent 面向不受信任的 IM 聊天用户时，建议启用）
• 支持 MCP 服务
• 插件系统（JSON-RPC 子进程）

技能

• 内置技能：code-runner、image-gen、data-analysis、translation、web-search、skill-creator
• 从 ClawHub 或 skills.sh 安装
• Agent 私有或全局共享

记忆

• MEMORY.md — 长期事实，由心跳自动更新
• 基于会话的上下文，完整保留历史记录
• 保留思考/推理内容，以便提取记忆

API

• 兼容 OpenAI 的 /v1/chat/completions（流式）
• /acp 上的 Agent Communication Protocol (ACP) 0.2 — Agent 发现、 清单、同步／异步／流式运行、事件、取消和会话
• 应用集成指南（也通过 /skills/agent-integration/SKILL.md 提供）：skills/agent-integration/SKILL.md
• ACP 集成指南：docs/acp.md
• Web 聊天 /api/chat/stream（SSE）
• 通过 /api/chat/subscribe 实时推送 Agent 消息（SSE）——无需刷新即可将定时任务触发及其他异步回复呈现在打开的聊天面板中
• 会话管理 /api/chat/sessions
• Agent CRUD /api/agents（?all=true 返回跨租户视图，仅限管理员）
• 按 Agent 管理调度器 /api/agents/{id}/cron（列出／切换／删除）
• 服务商管理 /api/config
• 安装技能 /api/skills/install（ClawHub + GitHub）
• API 密钥管理 /api/apikeys（按用户；层级：管理员／用户／Agent）
• 用户管理 /api/users（管理员）——顶层 CRUD，以及嵌套的 /api/users/{id}/apikeys 和 /api/users/{id}/agents，用于 由管理员驱动的配置。agents 端点接受 forkFrom，可将现有 Agent 的身份（SOUL / IDENTITY / 技能／模型默认值）克隆到新用户的命名空间中——这是“用户购买机器人” 流程的主要构建模块。每个用户的 agent_quota 限制非管理员可自行创建的 Agent 数量 （-1 = 无限制，0 = 仅限管理员配置）。
• 应用用户配置 POST /v1/users——第三方应用为每位终端用户创建稳定的 fastclaw user_id，基于 (api_key, external_id) 实现幂等。也可以在 /v1/chat/completions 上传递 user（或通过 X-Fastclaw-End-User 请求头），在首次调用时延迟创建

配置

引导配置仅通过环境变量完成。所有需要在运行时更改的内容 （服务商、模型、频道、默认值、沙盒开关）都存储在 数据库中，并通过控制面板或 fastclaw agents config 编辑。

环境变量	默认值	作用
FASTCLAW_HOME	~/.fastclaw	SQLite 数据库和技能文件夹的存放位置。
FASTCLAW_PORT	18953	网关 HTTP 端口。
FASTCLAW_BIND	loopback	loopback（127.0.0.1）或 all（0.0.0.0）。
FASTCLAW_STORAGE_TYPE	sqlite	sqlite 或 postgres。
FASTCLAW_STORAGE_DSN	空	Postgres DSN，例如 postgres://u:p@host:5432/db?sslmode=disable。为空时使用 $FASTCLAW_HOME/fastclaw.db 中的 SQLite。
FASTCLAW_STORAGE_AUTO_MIGRATE	true	启动时应用架构迁移。
FASTCLAW_REDIS_ENABLED	false	启用由 Redis 支持的频道租约和 Redis Stream 消息总线。设置 FASTCLAW_REDIS_ADDR 也会启用此功能。
FASTCLAW_REDIS_ADDR	启用时为 127.0.0.1:6379	多副本频道锁和共享入站／出站投递流使用的 Redis 地址。
FASTCLAW_REDIS_USERNAME	空	Redis ACL 用户名（如有需要）。
FASTCLAW_REDIS_PASSWORD	空	Redis 密码（如有需要）。
FASTCLAW_REDIS_DB	0	Redis 逻辑数据库编号。
FASTCLAW_REDIS_PREFIX	fastclaw	Redis 流和租约键的前缀。
FASTCLAW_SANDBOX_ENABLED	控制面板	覆盖“设置 → 运行时”开关。
FASTCLAW_SANDBOX_BACKEND	控制面板	docker 或 e2b。
FASTCLAW_SANDBOX_IMAGE	控制面板	Docker 镜像（Docker 后端）或模板 ID（E2B）。
FASTCLAW_OBJECT_STORE_*	未设置	用于分布式部署（多 Pod 技能／文件填充）的兼容 S3 对象存储。
FASTCLAW_LOG_LEVEL	info	debug / info / warn / error。

此列表之外的所有内容——服务商、模型、默认模型、技能 目录、频道、插件配置、调度器——都通过 Web UI（http://localhost:18953）或 CLI（fastclaw agents config、fastclaw provider、fastclaw skill）在运行时配置。

部署

本地

fastclaw                    # foreground (^C to stop)
fastclaw daemon start       # background (logs at ~/.fastclaw/daemon.log)
fastclaw daemon status
fastclaw daemon stop
fastclaw daemon install     # register as a launchd / systemd service

从命令行管理 Agent（fastclaw agents …）

fastclaw agents 子命令是对仪表板使用的同一存储的便捷封装。在这里创建的 Agent 会显示在 Web UI 中，反之亦然——每个 FASTCLAW_HOME 下始终只会有一个 fastclaw 部署。

# Zero to a chattable agent in one command. On a fresh install this
# creates an `admin` user (random password printed once) and starts
# the gateway daemon if it isn't already running.
fastclaw agents init alpha \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

# Set per-agent overrides (model, temperature, sandbox, …).
fastclaw agents config alpha set temperature 0.7
fastclaw agents config alpha set sandbox.enabled true

# Upload the agent's identity files.
fastclaw agents files put alpha SOUL.md ./SOUL.md
fastclaw agents files put alpha IDENTITY.md ./IDENTITY.md

# Inspect.
fastclaw agents ls
fastclaw agents config alpha get
fastclaw agents files ls alpha

# Tear down.
fastclaw agents rm alpha

CLI 会直接打开操作员的存储（sqlite 位于 ~/.fastclaw/fastclaw.db，或由 FASTCLAW_STORAGE_DSN 指向的位置），并通过网关使用的同一套代码路径写入数据。它不要求网关正在运行——但 agents init 会在后台启动网关，让新建的 Agent 立即可通过 http://localhost:18953 访问。后续 CLI 写入（config set、files put、rm、再次运行 init）会向正在运行的网关发送 SIGHUP，使其热重载而无需重启。Windows 不支持发送 SIGHUP，因此 CLI 会改为提示你运行 fastclaw daemon restart。

默认所有者是 admin 用户。在空数据库中，agents init 会创建该账号并生成密码（仅显示一次）；在已有数据的数据库中，它要求 admin 已存在，或 --username 指向一个现有用户。

解析 Agent

CLI 命令接受显示名称或 agt_… ID：

• fastclaw agents config alpha get — 按显示名称查找（必须唯一）
• fastclaw agents config agt_d3c4a5… get — 按 ID 查找

如果同一文本匹配某个 Agent 的 ID 和另一个 Agent 的显示名称，CLI 会报告歧义，而不会自行猜测。

通过 agents init <name> 创建 Agent 时，name 是显示名称，ID 会自动生成。要更新通过仪表板创建的 Agent，请显式传入其 ID：

fastclaw agents init "Cool Agent" --id agt_d3c4a5...

配置键

每个 Agent 的配置（以 Agent ID 为准，保存在 scope=agent 下）：

• model、temperature、maxTokens、thinking、policy
• sandbox、sandbox.enabled、sandbox.backend、sandbox.image、sandbox.network

系统级配置（保存在 scope=system 下）：

• plugins、plugins.<name>
• skills.install、skills.entries、skillsLearner
• tools.providers、tools.categories
• objectstore、taskqueue、heartbeat、memory、privacy、hooks、teams

Provider 配置位于 scope=system，并通过 provider.<name>.<field> 指定：

fastclaw agents config alpha set provider.openai.apiKeyEnv OPENAI_API_KEY
fastclaw agents config alpha set provider.openrouter.apiBase https://openrouter.ai/api/v1
fastclaw agents config alpha set provider.openai.model gpt-4o      # adds; idempotent
fastclaw agents config alpha set provider.openai.models '[]'        # explicit clear

内置的 Provider 预设包括 openai、openrouter、anthropic、ollama、groq、deepseek、mistral——--api-key-env 会从指定的环境变量填充 apiKey，其余配置来自预设。

Agent 系统文件

CLI 会读写与仪表板文件编辑器使用的同一个 agent_files 表。允许使用的文件名：SOUL.md、IDENTITY.md、USER.md、BOOTSTRAP.md、MEMORY.md、HEARTBEAT.md、AGENTS.md、TOOLS.md、agent.json。

子命令	用途
agents init <name>	创建或更新 Agent（Provider/模型/沙箱/文件）
agents ls	列出存储中的所有 Agent
agents config <name> get|set [key] [value]	读取或更新配置值
agents files ls|put|get <name>	读取/写入 Agent 的系统文件
agents rm <name>	删除 Agent 记录及其系统文件

从命令行管理 API 密钥（fastclaw apikey …）

为外部集成签发并管理程序化凭据。

密钥类型

type	作用范围	用例
admin	完整的平台访问权限，可访问所有 Agent	管理员自动化、CI/CD
user	所有者的 Agent；支持使用 X-Fastclaw-End-User 配置 app_user	SaaS 代理层、多租户应用
agent	仅限显式指定的 Agent 列表；无法创建 Agent	机器人、单一用途集成

命令

# Create a key (token shown once — save immediately)
fastclaw apikey create --name "my-key" --type user [--owner <user-id>]

# List keys for a user (defaults to first super_admin)
fastclaw apikey list [--owner <user-id>]

# Delete a key
fastclaw apikey delete --id <apikey-id>

# Rotate a key (old token invalidated, new token shown once)
fastclaw apikey rotate --id <apikey-id>

选项：

• --name（必填）：便于识别的密钥名称
• --type（默认值为 user）：admin、user 或 agent
• --owner（可选）：所有者用户 ID；默认为第一个 super_admin

多租户 app_user 流程

将 type=user 密钥与 X-Fastclaw-End-User 请求头结合使用，无需在 FastClaw 中预先注册用户，即可隔离各最终用户的数据：

Authorization: Bearer <user-key-token>
X-Fastclaw-End-User: <your-app-user-id>

FastClaw 会为每个唯一的 (api_key_id, external_id) 对延迟创建一个稳定的内部用户。会话、记忆和文件都按最终用户完全隔离。

Docker

cd deploy/docker && ./start.sh

Kubernetes

env:
  - name: FASTCLAW_BIND
    value: "all"
  - name: FASTCLAW_STORAGE_TYPE
    value: "postgres"
  - name: FASTCLAW_STORAGE_DSN
    valueFrom:
      secretKeyRef:
        name: fastclaw-db
        key: dsn
  - name: FASTCLAW_OBJECT_STORE_ENDPOINT
    value: "s3.amazonaws.com"
  - name: FASTCLAW_OBJECT_STORE_BUCKET
    value: "fastclaw-skills"

不会挂载配置文件——启动配置仅通过环境变量提供。完整清单请参阅 deploy/k8s/。

构建

make build                  # builds the web bundle and the Go binary → bin/fastclaw
make install                # installs to $HOME/.local/bin (override with PREFIX=)
make release-local          # cross-compile darwin / linux / windows into dist/

Makefile 通过 -ldflags 将版本、提交和构建日期写入二进制文件。CI 也使用这些目标——请参阅 .github/workflows/。

许可证

FastClaw 基于 Apache License 2.0，并附加了其他条件，采用 FastClaw Community License 进行源代码可用授权。

简而言之：

• ✅ 可将其作为自有产品的后端用于商业用途
• ✅ 可在组织内部部署
• ❌ 未获得商业许可证时，不得将 FastClaw 托管为面向无关联组织的多租户 SaaS
• ❌ 不得移除或修改仪表板 UI 中的 FastClaw 品牌标识

完整的 Apache 2.0 文本及附加条款收录在 LICENSE 文件中。商业许可咨询请联系：[email protected]。