Storage Providers
Where uploaded file bytes are physically stored — local disk or Alibaba Cloud OSS.
Storage Providers
A storage provider controls where the raw bytes of uploaded files are kept. It only affects the physical location of file data — not retrieval quality or agent behavior.
Recommended default
Use Local File System unless you have a specific reason to offload file storage to an external backend.
Supported types
Local File System
Files are stored on the server's local disk. This is the default and requires no additional configuration.
- Best for: single-server deployments, development environments, on-premise installations where you manage your own disk
- No API key required
- No extra cost beyond disk space
Files are written to the configured upload directory on the server running OpenAgent. If you're running behind a load balancer or across multiple nodes, all nodes must share the same filesystem (e.g. a network mount) or you will get inconsistent file access.
Alibaba Cloud OSS
Files are uploaded to Alibaba Cloud Object Storage Service (OSS).
- Best for: deployments on Alibaba Cloud infrastructure, or when you need scalable cloud object storage
- API Key required: your Alibaba Cloud Access Key ID and Access Key Secret
- Region and bucket: configure the OSS region, bucket name, and endpoint
The original file bytes are stored in OSS. Processing (text extraction, chunking, embedding) still happens within OpenAgent — the storage provider only determines where the file bytes land.
Casdoor (default fallback)
When no storage provider is explicitly configured on a Store, OpenAgent falls back to using Casdoor's built-in storage. This requires Casdoor to be configured and available. For production deployments, explicitly configure Local File System or Alibaba Cloud OSS.
Adding a provider
- Providers → Add Provider, category Storage
- Choose Local File System or Alibaba Cloud OSS
- For Alibaba Cloud OSS, enter your Access Key ID (Client ID), Access Key Secret (Client Secret), Region, and Bucket
- Save
Then edit the Store and set Storage Provider to the provider you created.
Setting a default
If you have only one storage provider configured, all new Stores will default to it. If you have multiple providers, select the one you want in the Storage Provider field on each Store individually.
Changing the storage provider on an existing Store
Changing the Storage Provider on a Store does not migrate existing files. Files already uploaded remain in their original storage location. Only new uploads after the change will go to the new provider.
If you need all files in the same storage backend, delete the existing Files and re-upload them after switching the provider.
What the storage provider does not affect
- File metadata — name, size, status (
Pending,Processing,Finished,Error), and Store association are always in OpenAgent's database - Vectors — embeddings are always stored in OpenAgent's Vector table, regardless of storage provider
- File processing — text extraction and chunking happen within OpenAgent after the file is stored, independently of where the bytes live
- Retrieval — vector similarity search does not access the raw file bytes; it only uses Vectors
In practice, most deployments use Local File System throughout. Switch to Alibaba Cloud OSS only if you need scalable cloud object storage or are running on Alibaba Cloud infrastructure.
The storage provider is a low-visibility setting. It doesn't affect retrieval quality, agent behavior, or conversation performance. Set it once when configuring a new Store and leave it alone.