mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-05 06:59:23 +00:00
ee6e54233a
Document the deny-by-default allow-list behavior, the new CREWAI_TOOLS_ALLOWED_DIRS env var for extending allowed roots, the fail-closed behavior when cwd is the filesystem root, and the CREWAI_TOOLS_ALLOW_UNSAFE_PATHS escape hatch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
71 lines
3.5 KiB
Plaintext
71 lines
3.5 KiB
Plaintext
---
|
|
title: File Write
|
|
description: The `FileWriterTool` is designed to write content to files.
|
|
icon: file-pen
|
|
mode: "wide"
|
|
---
|
|
|
|
# `FileWriterTool`
|
|
|
|
## Description
|
|
|
|
The `FileWriterTool` is a component of the crewai_tools package, designed to simplify the process of writing content to files with cross-platform compatibility (Windows, Linux, macOS).
|
|
It is particularly useful in scenarios such as generating reports, saving logs, creating configuration files, and more.
|
|
This tool handles path differences across operating systems, supports UTF-8 encoding, and automatically creates directories if they don't exist, making it easier to organize your output reliably across different platforms.
|
|
|
|
## Installation
|
|
|
|
Install the crewai_tools package to use the `FileWriterTool` in your projects:
|
|
|
|
```shell
|
|
pip install 'crewai[tools]'
|
|
```
|
|
|
|
## Example
|
|
|
|
To get started with the `FileWriterTool`:
|
|
|
|
```python Code
|
|
from crewai_tools import FileWriterTool
|
|
|
|
# Initialize the tool
|
|
file_writer_tool = FileWriterTool()
|
|
|
|
# Write content to a file in a specified directory
|
|
result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
|
|
print(result)
|
|
```
|
|
|
|
## Arguments
|
|
|
|
- `filename`: The name of the file you want to create or overwrite.
|
|
- `content`: The content to write into the file.
|
|
- `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`.`). If the directory does not exist, it will be created.
|
|
|
|
## Path confinement
|
|
|
|
Because `filename` and `directory` may be supplied at runtime by an agent acting on untrusted content, `FileWriterTool` confines writes to an **allow-listed set of root directories**. The resolved target (after expanding symlinks and `..`) must fall inside one of these roots or the write is rejected — a `directory` argument pointing outside them (e.g. `~/.ssh`, `/etc`) no longer grants write access.
|
|
|
|
The allow-list is, by default, the current working directory. You can extend it for deployments that legitimately write elsewhere:
|
|
|
|
- `CREWAI_TOOLS_ALLOWED_DIRS` — one or more additional root directories, separated by the OS path separator (`:` on Linux/macOS, `;` on Windows).
|
|
|
|
```shell
|
|
# Allow writes under /data and /workspace in addition to the cwd
|
|
export CREWAI_TOOLS_ALLOWED_DIRS="/data:/workspace"
|
|
```
|
|
|
|
<Warning>
|
|
If the process runs with its working directory set to the filesystem root (`/`) — common in containers started without a `WORKDIR` — the tool will **not** fall back to allow-listing the entire filesystem. Writes fail with a `ValueError` until you set `CREWAI_TOOLS_ALLOWED_DIRS` to an explicit directory. Set a `WORKDIR` (or the env var) in such deployments.
|
|
</Warning>
|
|
|
|
The `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` escape hatch disables path validation entirely. It is intended only for trusted local development and should not be set in any environment that runs agent-generated or otherwise untrusted instructions.
|
|
|
|
## Conclusion
|
|
|
|
By integrating the `FileWriterTool` into your crews, the agents can reliably write content to files across different operating systems.
|
|
This tool is essential for tasks that require saving output data, creating structured file systems, and handling cross-platform file operations.
|
|
It's particularly recommended for Windows users who may encounter file writing issues with standard Python file operations.
|
|
|
|
By adhering to the setup and usage guidelines provided, incorporating this tool into projects is straightforward and ensures consistent file writing behavior across all platforms.
|