OpenWorker Setup Guide

From download to your first automated task in under 10 minutes. Every step explained with screenshots and troubleshooting tips.

Start Setup ← Back to Guide

System Requirements for OpenWorker

Before installing OpenWorker, make sure your machine meets these minimum requirements. The app is lightweight but local AI models need adequate RAM.

Operating System

macOS 12 Monterey or later (Windows coming soon)

RAM

8 GB minimum, 16 GB recommended for local models

Disk Space

500 MB for the app, plus model storage if using Ollama

API Key

At least one provider key (OpenAI, Anthropic, Google, etc.) or Ollama installed

Step-by-Step OpenWorker Installation

Follow these five steps to get OpenWorker running on your Mac. Each step includes what to expect and how to verify it worked.

Download OpenWorker

Visit the official OpenWorker website and download the macOS installer. The app is a standard .dmg file — drag it to your Applications folder like any other Mac app. The initial download is around 120 MB.

Grant System Permissions

On first launch, macOS will ask you to approve OpenWorker in System Settings → Privacy & Security. The app needs file system access to work with your documents and accessibility permissions for integration with other desktop apps.

Add Your API Key

Open OpenWorker and navigate to Settings → Models. Paste your API key from any supported provider. You can add multiple keys and switch between models per task. For a free start, install Ollama and run a local model with zero API cost.

Connect Your First Integration

Go to Settings → Integrations and select a tool you use daily — Slack, Gmail, or Google Calendar are great starting points. Most integrations use one-click OAuth authentication. OpenWorker will request only the permissions it needs.

Run Your First Task

Type a natural language request in the chat window. Start simple: 'Summarize my unread emails from today' or 'What meetings do I have tomorrow?' OpenWorker will show its execution plan and ask for approval before taking action.

Connecting Integrations to OpenWorker

OpenWorker connects to your everyday tools through standardized OAuth flows or manual API token entry. Each integration grants the agent specific permissions — read-only access for monitoring tasks, or read-write access for agents that need to send messages or update records.

The most popular first integrations are Slack (for message triage and team communication), Google Calendar (for scheduling optimization), and Gmail (for email drafting and summarization). These three integrations alone cover the majority of daily knowledge worker tasks that OpenWorker can automate.

For development teams, connecting GitHub and Linear or Jira lets OpenWorker generate pull request summaries, triage issues, and compile sprint reports. Enterprise users can also connect HubSpot for CRM automation and Notion for documentation updates.

Each integration stores its credentials locally on your machine. OpenWorker never transmits your OAuth tokens to any server other than the integration provider itself. You can revoke any integration at any time through Settings → Integrations without affecting other connections.

Setting Up OpenWorker Permission Modes

OpenWorker's permission system is the safety layer between the AI agent and your real-world tools. Every action the agent considers is classified into one of four risk types: read (viewing files and data), write_local (modifying local files), exec (running commands), and external (calling APIs or sending messages).

Five permission modes control how OpenWorker handles these risk types. In Supervised mode, every action requires your approval. Cautious mode auto-approves reads but asks for everything else. Standard mode auto-approves reads and local writes. Autonomous mode only pauses for external actions. And Full Auto runs everything without interruption.

Our recommendation is to start with Cautious mode. This lets OpenWorker gather information freely while requiring your sign-off before it changes any file or contacts any external service. Once you've seen how the agent handles your specific workflows — typically after a week of daily use — you can move to Standard mode for a smoother experience.

OpenWorker Troubleshooting

Common issues and their solutions when setting up OpenWorker for the first time.

Problem: App won't open on macOS

Fix: Right-click the app and select Open, then click Open in the dialog. This bypasses Gatekeeper for unsigned apps. Alternatively, go to System Settings → Privacy & Security and click 'Open Anyway.'

Problem: API key not recognized

Fix: Double-check that you copied the full key without leading or trailing spaces. Some providers require you to create a project-specific key. Make sure your account has billing enabled and the key has the correct permissions.

Problem: Ollama models not appearing

Fix: Ensure Ollama is running (check for the llama icon in your menu bar). Run 'ollama list' in Terminal to verify installed models. OpenWorker detects Ollama automatically when it is running on the default port (11434).

Problem: Integration OAuth fails

Fix: Clear your browser cookies for the integration provider and try again. Some corporate Google Workspace or Microsoft 365 accounts require admin approval for third-party OAuth connections.

Problem: Slow response times

Fix: Response speed depends on your chosen model and provider. Cloud models like GPT and Claude are faster than large local models. For local Ollama models, ensure you have enough RAM — a 7B model needs about 4 GB, a 13B model needs 8 GB.

OpenWorker Setup FAQ

How long does OpenWorker setup take?

The entire process from download to your first completed task takes under 10 minutes. Most of that time is spent on the one-time OAuth flow for connecting integrations like Slack or Gmail.

Can I use OpenWorker without an API key?

Yes, if you install Ollama and download a local model. Ollama runs models entirely on your machine with no API key or internet connection required. Models like Llama 3, Mistral, and Qwen work well for general tasks.

Does OpenWorker work with corporate SSO?

OpenWorker connects to corporate tools through standard OAuth flows. If your organization uses SSO for Slack, Google Workspace, or Microsoft 365, the OAuth flow should work normally. Some strict enterprise policies may require IT admin approval.

How do I update OpenWorker?

OpenWorker checks for updates automatically and prompts you when a new version is available. You can also manually check for updates in Settings → About. Updates are incremental and typically take under a minute to apply.

Can I run OpenWorker on multiple Macs?

Yes. Install OpenWorker on each machine and add your API keys separately. Integration connections are per-device since OAuth tokens are stored locally. Your task history does not sync between devices.

What happens if I revoke an integration?

OpenWorker will show an error when it tries to use that integration and ask you to reconnect. Revoking an integration does not affect your other connections or task history.

Is there a command-line version of OpenWorker?

OpenWorker is primarily a desktop application. The underlying agent server is a Python FastAPI service that advanced users can interact with directly through its local API, but the desktop GUI is the recommended interface.

How do I configure permission modes in OpenWorker?

Go to Settings → Permissions. OpenWorker offers five permission modes ranging from fully supervised (approve every action) to more autonomous. Start with supervised mode and gradually increase autonomy as you understand how the agent handles your workflows.

OpenWorker Is Ready

Now that your OpenWorker installation is complete, explore the model comparison guide to find the best AI model for your workflows.

Compare Models See Alternatives