0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/templates/template-claw-assistant
Justin Levine afc9479bdf
feat(templates): read the model from AGENT_MODEL in Claw Assistant (#29747)
## Description

Claw Assistant now reads its chat model from `AGENT_MODEL` and falls
back to `mastra/openai/gpt-5.4`, so nothing changes until Mastra
Platform sets it. This lets Platform's template form offer a model
choice (PLTFRM-3312). Web search now uses the Gateway web search tool
from docs-expert instead of OpenAI's provider tool, so it works on any
model and the agent's instructions stay true.

## Related issue(s)

Linear PLTFRM-3315

## Type of change

- [x] New feature (non-breaking change that adds functionality)

## Checklist

- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

Verified: `mastra build` passes and `tsc` is clean against the published
packages.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## ELI5

Claw Assistant can now use the model named in `AGENT_MODEL`; if the
variable is empty or missing, it uses `mastra/openai/gpt-5.4`. Web
search uses a separate Gateway tool, so it does not depend on the
selected chat model.

## Changes

- Documented `AGENT_MODEL` in `.env.example` and the README, including
example model IDs and the default.
- Added a Gateway web-search tool that sends searches through
`openai/gpt-5-mini` with `openrouter:web_search` and returns an answer
with deduplicated citations.
- Replaced the OpenAI SDK web-search tool with the Gateway tool and
removed the `@ai-sdk/openai` dependency.

## Checks

- Build and test results: not available.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
History 2026-11-09 18:02:00 +00:00
..
src/mastra feat(templates): read the model from AGENT_MODEL in Claw Assistant (#29747) 2026-11-09 18:02:00 +00:00
workspace/skills feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
.env.example feat(templates): read the model from AGENT_MODEL in Claw Assistant (#29747) 2026-11-09 18:02:00 +00:00
.gitignore feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
package.json feat(templates): read the model from AGENT_MODEL in Claw Assistant (#29747) 2026-11-09 18:02:00 +00:00
pnpm-workspace.yaml feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
README.md feat(templates): read the model from AGENT_MODEL in Claw Assistant (#29747) 2026-11-09 18:02:00 +00:00
tsconfig.json feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00

Claw — Autonomous Personal Assistant

An autonomous assistant that operates a computer to finish multi-step tasks — read/write files, run shell commands in a sandboxed workspace, browse the web with Playwright (@mastra/agent-browser), search the web through Mastra's Gateway, and follow reusable skills checked into workspace/skills/.

Claw has resource-scoped observational memory, so it remembers your preferences and context across threads.

Prerequisites

  • Node.js >= 22.13.0
  • A Gateway API key — get one at gateway.mastra.ai
  • (Optional) A Turso database; for local dev, the default file:./mastra.db works.
  • Playwright's Chromium browser for local runs, or BROWSER_CDP_URL for a hosted Chrome/Browserbase/Browserless instance in server deployments.

Setup

npm install
cp .env.example .env
# fill in MASTRA_GATEWAY_API_KEY (TURSO_DATABASE_URL defaults to file:./mastra.db)
npm run dev

Then open Mastra Studio (URL printed by npm run dev) and chat with the claw agent.

Workspace layout

workspace/
├── skills/
│   ├── general-tasks/SKILL.md
│   └── research-tasks/SKILL.md
└── … your files end up here

The agent can only read/write inside workspace/ (or whatever CLAW_WORKSPACE_DIR points at). The sandboxed shell runs with that directory as its CWD.

Adding skills

Create a new folder under workspace/skills/<skill-name>/ with a SKILL.md:

---
name: my-skill
description: Short summary the agent uses to decide when to apply this skill.
version: 1
metadata:
  tags: [optional, tags]
---

# Process

1. Step one.
2. Step two.

The agent will pick up new skills on the next request.

Environment variables

Variable Purpose
MASTRA_GATEWAY_API_KEY Routes the chat model and web search through the Gateway.
AGENT_MODEL Optional model router id. Defaults to mastra/openai/gpt-5.4.
TURSO_DATABASE_URL libSQL/Turso URL. Defaults to file:./mastra.db.
TURSO_AUTH_TOKEN Turso auth token (omit for local file DB).
CLAW_WORKSPACE_DIR Override the workspace root directory.
BROWSER_HEADLESS Set to false to launch the browser headfully. Defaults to headless.
BROWSER_CDP_URL Optional hosted browser CDP URL for server deployments.

Agent Editor

This template enables the code-backed Agent Editor with new MastraEditor({ source: 'code', codePath: 'mastra/editor' }). Edits made in Studio are written as deterministic JSON overrides under mastra/editor/agents/, so Mastra Platform can open GitHub pull requests for agent changes instead of only saving them to the database.