https://github.com/sohutv/fastclaw
Fastclaw is a local terminal AI agent built with Rust. It works through an OpenAI-compatible model interface and supports streaming output, reasoning display, conversation context, and tool calls (such as shell and reload-self).
https://github.com/sohutv/fastclaw
Last synced: 3 months ago
JSON representation
Fastclaw is a local terminal AI agent built with Rust. It works through an OpenAI-compatible model interface and supports streaming output, reasoning display, conversation context, and tool calls (such as shell and reload-self).
- Host: GitHub
- URL: https://github.com/sohutv/fastclaw
- Owner: sohutv
- License: apache-2.0
- Created: 2026-04-01T09:29:22.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T10:42:07.000Z (3 months ago)
- Last Synced: 2026-04-07T09:00:30.223Z (3 months ago)
- Language: Rust
- Size: 1.61 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
- Notice: NOTICE
Awesome Lists containing this project
README
# Fastclaw
English | [中文](./README.zh-cn.md)
Fastclaw is a local AI agent built with Rust. It supports OpenAI-compatible model providers, multi-channel interaction (CLI and DingTalk), streaming output, conversation history, scheduled task execution, and tool calls.
## Features
- Async runtime based on `tokio` + `rig-core`
- OpenAI-compatible model provider integration
- Channels:
- CLI channel (`--channel Cli`)
- DingTalk channel (`--channel Dingtalk`, enabled by default feature)
- Streaming reasoning and final answer output
- Built-in tools:
- `shell`: execute shell commands in workspace
- `current-time`: return local time in RFC3339 format
- `task-list`, `task-create`, `task-detail-get`, `task-update`, `task-del`
- `websearch` (only when `[websearch]` is configured)
- Session history persistence and history compaction support (`/compact`)
- Background heartbeat scheduler for cron tasks
- One-command onboarding for workdir, default config, and workspace templates
## Requirements
- Rust stable with `edition = 2024`
- Cargo
- Access to an OpenAI-compatible API service
## Build
```bash
git clone
cd fastclaw
cargo build
```
If you only need CLI and want to avoid DingTalk dependency:
```bash
cargo build --no-default-features --features "model_provider_openai_compatible,channel_cli_channel,volcengine"
```
## CLI Commands
```bash
fastclaw
```
Available subcommands:
- `onboard init-config`: initialize workdir and default files
- `start`: start agent runtime
Examples:
```bash
cargo run -- --help
cargo run -- onboard init-config --help
cargo run -- start --help
```
## Quick Start
### 1. Initialize Workdir
Default workdir is `~/.fastclaw`:
```bash
cargo run -- onboard init-config
```
Use a custom path:
```bash
cargo run -- onboard init-config --path /absolute/path/to/fastclaw-home
```
If directory already exists, add `--rewrite`:
```bash
cargo run -- onboard init-config --path /absolute/path/to/fastclaw-home --rewrite
```
### 2. Edit `config.toml`
A newly generated `config.toml` currently looks like:
```toml
default_model_provider = ""
default_model = ""
default_show_reasoning = true
[agent_settings]
[model_providers]
[log_config]
level = "Info"
[log_config.logger]
logs_dir = "./logs"
[heartbeat_config]
interval = 60
```
Minimal usable example:
```toml
default_model_provider = "openai"
default_model = "gpt-4.1-mini"
default_show_reasoning = true
[model_providers.openai]
provider_type = "OpenaiCompatible"
api_key = "sk-xxx"
api_url = "https://api.openai.com/v1"
[model_providers.openai.models.gpt-4.1-mini]
vision = true
audio = false
video = false
document = false
websearch = false
reasoning = true
tool = true
reranker = false
embedding = false
max_tokens = 65536
[heartbeat_config]
interval = 60
[log_config]
level = "Info"
[log_config.logger]
logs_dir = "./logs"
```
Optional web search config (`volcengine` feature):
```toml
[websearch]
type = "volcengine"
api_url = "https://"
api_key = ""
```
Optional DingTalk config (when `channel_dingtalk_channel` is enabled):
```toml
[dingtalk_config.credential]
client_id = "..."
client_secret = "..."
[dingtalk_config.allow_session_ids]
"staff_id_or_group_key" = { Master = { val = "owner", settings = {} } }
```
### 3. Start Agent
```bash
cargo run -- start --channel Cli
```
With custom workdir:
```bash
cargo run -- start --channel Cli --workdir /absolute/path/to/fastclaw-home
```
## CLI Interaction
After startup, enter message at `>>`.
Console commands:
- `/compact --ratio <0.2~1.0>`: compact current session history
- `/showreasoning on|off`: currently parsed but **not implemented** (see Known Issues)
Per-round usage footer:
- `<>`
## Generated Layout
`onboard init-config` creates:
```text
/
config.toml
db.sqlite
workspace/
AGENTS.md
BOOTSTRAP.md
HEARTBEAT.md
IDENTITY.md
MEMORY.md
SOUL.md
TOOLS.md
USER.md
cron/README.md
memory/README.md
sessions/README.md
skills/README.md
state/README.md
```
## Logging
`[log_config]` supports:
- `level`: `Error` / `Warn` / `Info` / `Debug`
- `logger`:
- `Stdout`
- `File { logs_dir = "./logs" }` (relative path resolves to `/logs`)
## Development
```bash
cargo fmt
cargo clippy --all-targets --all-features
cargo test --all-features
```
## Known Issues
- `/showreasoning on|off` triggers `unimplemented!()` in current code path.
- In CLI channel, reasoning text is still printed even when `default_show_reasoning = false`; only heading/closing markers are gated.
- `cargo test --all-features` requires `VOLCENGINE_WEBSEARCH_API_URL` and `VOLCENGINE_WEBSEARCH_API_KEY` for `volcengine` websearch test.
## Notes
- `start --workdir` must point to initialized workdir containing `config.toml`.
- Startup fails if log directory is not writable.
- Model creation fails if `default_model_provider`, `default_model`, or provider model settings are missing.