2026-09-02 01:05:41 +08:00
commit 04bac1f6e2
2200 changed files with 489415 additions and 0 deletions
@@ -0,0 +1,59 @@
---
title: "Add a custom LLM"
description: "How to connect a custom provider with OpenWork"
---
<Note>
**Local provider setup.** A custom provider can stay entirely in your workspace. OpenWork remains free, and you do not need to sign in to OpenWork Cloud. For centrally managed team access, see [Adding a managed LLM provider](/cloud/share-with-your-team/managed-llm-provider).
</Note>
Because `OpenWork` is built on `OpenCode` primitives, we support everything that you could modify in `.opencode.json`, like adding a [model](https://opencode.ai/docs/models/). However, our recommendation is to add it to `/path-to-your-workspace/.config/opencode/opencode.json` instead of modifying `~/.config/opencode/opencode.json`.
Inside `/path-to-your-workspace/.config/opencode/opencode.json`:
```
{
  "provider": {
    "my-api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My model",
      "options": {
        "baseURL": "https://your API address/v1"
      },
      "models": {
        "model-name": {
          "name": "Model name"
        }
      }
    }
  }
}
```
### Functional example: Ollama (Qwen3 8B)
This setup a local [Ollama](https://docs.ollama.com/api/openai-compatibility) instance running `qwen3:8b`. 
```
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3:8b": {
          "name": "Qwen3 8B"
        }
      }
    }
  }
}
```
Pull the model first with `ollama pull qwen3:8b`, then make sure the Ollama server is reachable at `http://localhost:11434` with `ollama serve`
Open your desktop, change the provider name and voila! You have an fully local LLM running in your machine.
For teams, manage the provider in OpenWork Cloud under [Models > Bring your Own Keys](/cloud/share-with-your-team/managed-llm-provider), then make it available from `Settings > Cloud Providers` in the desktop app.
@@ -0,0 +1,50 @@
---
title: "Add a custom MCP server"
description: "Connect a custom or local MCP server that is not available through OpenWork Connect"
---
<Note>
**Local workspace setup.** Custom MCP servers are supported without an OpenWork Cloud account, so this path stays free and local to the current workspace. For a connection managed and assigned by your organization, use [OpenWork Cloud Connectors](/cloud/share-with-your-team/shared-mcp-connections).
</Note>
Use this guide only when you need a custom or local MCP server that is not available through OpenWork Connect.
For Gmail, Google Calendar, Google Drive, Slack, Notion, Linear, and other
managed services, follow [Connect your services](/start-here/connect-your-stack/connect-services).
Connecting a custom app with OpenWork takes four clicks.
- In the desktop app, open `Settings` \> `Library`, expand `Advanced settings`, then click `Add workspace MCP`
<Frame>
  ![Library page with Advanced settings expanded, showing the Add workspace MCP button](/images/library-advanced-settings.png)
</Frame>
The MCP is added to the current workspace.
<Frame>
  ![Add workspace MCP dialog with app name, server URL, and OAuth options](/images/library-add-mcp-modal.png)
  Indicate whether the server requires OAuth.
</Frame>
This setup is intended for servers that support dynamic OAuth client registration.
<Frame>
  ![OAuth approval page for MCP server](/images/mcp-oauth-approval-page.png)
</Frame>
Complete the provider's OAuth approval flow in your browser. It should redirect
back to OpenWork. If a custom MCP needs behavior OpenWork does not support,
[open an issue](https://github.com/different-ai/openwork/issues/).
### Troubleshooting
Some MCP servers do not support dynamic client registration. If the server gives you a pre-registered OAuth client ID and client secret, add it through `Add workspace MCP` > `OAuth on this device`.
For an advanced local Slack setup, follow
[Connect Slack as a custom MCP](/start-here/connect-your-stack/connect-slack-mcp).
<Frame>
  ![Error when MCP server does not support dynamic client registration](/images/mcp-dynamic-registration-error.png)
</Frame>
@@ -0,0 +1,57 @@
---
title: "Add Anthropic API key"
description: "Create an Anthropic API key and use it in OpenWork"
---
<Note>
**Local provider setup.** The key you add here is for your desktop app. OpenWork remains free, and you do not need to sign in to OpenWork Cloud. To manage Anthropic access for a team, use [a managed LLM provider](/cloud/share-with-your-team/managed-llm-provider).
</Note>
Anthropic has disabled 3rd party authentication for their OAuth. In order to continue supporting Anthropic based models in OpenWork, we now default to manual API key entry for Anthropic.
That means you create the key in Anthropic first, then paste it into OpenWork.
## Before you start
- You need an Anthropic account at [platform.claude.com](https://platform.claude.com).
- Your Claude subscription and your Anthropic API billing are not always the same thing, so make sure API access is enabled on your Anthropic account.
- Treat the key like a password. Anthropic will only show the full value when you create it.
If this key should be managed for a team, add Anthropic once under `Models > Bring your Own Keys` in OpenWork Cloud. Members receive it through `Settings > Cloud Providers` instead of pasting it into each workspace separately.
## Create the key in Anthropic
1. Sign in at [platform.claude.com](https://platform.claude.com).
2. Open the `API Keys` page.
<Frame>
  ![Anthropic API Keys page](/images/anthropic-key.png)
</Frame>
3. Click `Create Key`.
4. Give the key a recognizable name like `OpenWork`.
<Frame>
  ![Anthropic Create Key dialog](/images/anthropic-openwork-key.png)
</Frame>
5. Copy the new key right away. It should look like `sk-ant-...`.
## Add the key to OpenWork
1. Open `Settings` in OpenWork.
2. Go to `Connect Provider` and choose `Anthropic`.
3. Paste the API key into the manual key field.
4. Save the provider, then choose an Anthropic model in chat.
<Frame>
  ![How to add a new provider in OpenWork](/images/openwork-providers.png)
</Frame>
## Common issues
- If the key is rejected, make sure you copied the full value without extra spaces.
- If you cannot see `API Keys`, check that your Anthropic account has API access and billing set up.
- If you lose the key, create a new one in Anthropic and update OpenWork with the new value.
The same general process applies to most providers that use manual API keys: create the key in the provider's developer console, copy it once, and paste it into OpenWork.
@@ -0,0 +1,71 @@
---
title: "Connect your services"
description: "Sign in to OpenWork and connect the accounts your agent can use"
---
<Info>
**OpenWork Cloud organization setup.** This path requires an OpenWork Cloud sign-in and an organization that has made services available to you. To stay local, keep using OpenWork for free and [add a custom MCP server](/start-here/connect-your-stack/add-an-mcp-server) to your workspace. Admins can manage team connections with [Connectors](/cloud/share-with-your-team/shared-mcp-connections).
</Info>
Use `Settings` > `OpenWork Connect` for services your organization makes available,
including Gmail, Google Calendar, Google Drive, Slack, Notion, and Linear. This
is the recommended setup for everyday integrations.
## Before you start
Connect requires signing in to an OpenWork account and joining an organization
that has Connect enabled. This is separate from signing in to an LLM provider
such as ChatGPT.
1. Open the OpenWork desktop app.
2. Click `Sign in`, or open `Settings` > `OpenWork Connect` and choose `Sign in`.
3. Complete sign-in in your browser and return to OpenWork.
4. Choose the OpenWork organization you want to use if prompted.
If Connect is not available for your organization, ask an organization admin
to enable it.
## Connect an account
1. Open `Settings` > `OpenWork Connect`.
2. Find the service under `Needs your sign-in`.
3. Click `Connect` and approve access on the provider's sign-in page.
4. Return to OpenWork. The service moves to `Ready to use` automatically.
Some connections are managed by your organization. If a service is not
listed, ask an organization admin to publish it from the OpenWork Cloud
`Connectors` page and grant you access.
## Ask your agent to use it
You do not need to know an MCP server name or tool name. Ask for the outcome
you want, for example:
- “Summarize my five newest emails.”
- “Find the Q3 launch page in Notion.”
- “What meetings do I have tomorrow?”
The agent searches the live capabilities available to your signed-in account,
then executes an exact match. If an account still needs attention, it should
send you back to `Settings` > `OpenWork Connect` with the action to take instead of
telling you to add an MCP server.
## Connect, connectors, and connections
- **Connect** is the member-facing page in the desktop app for signing in to
  services and checking connection readiness.
- A **connector** is an MCP service your organization adds on its own, without
  wrapping it in a plugin. Organization admins publish connectors from the
  OpenWork Cloud `Connectors` page and grant member or team access.
- A **connection** is your own signed-in instance of a connector — one
  connector, instantiated per user with that user's account.
- The **MCP Gateway** is the hosted endpoint that lets external MCP clients
  use capabilities from an OpenWork organization. See
  [OpenWork MCP Gateway](/cloud/run-in-the-cloud/cloud-mcp).
- **Add an MCP server** is the advanced path for a custom or local server that
  your organization does not provide through Connect.
If you are building a custom integration, continue with
[Add an MCP server](/start-here/connect-your-stack/add-an-mcp-server). If you
are an organization admin, see
[Sharing MCP connections with your team](/cloud/share-with-your-team/shared-mcp-connections).
@@ -0,0 +1,126 @@
---
title: "Connect Slack as a custom MCP"
description: "Advanced local setup for Slack's MCP server with a pre-registered OAuth app"
---
This is the advanced local setup. For the recommended member experience,
sign in to OpenWork and start with
[Connect your services](/start-here/connect-your-stack/connect-services).
Slack's official MCP server does not support automatic OAuth client registration. To connect it as a custom local MCP in OpenWork, ask a Slack admin to create or approve a Slack app for MCP, then add the app's OAuth client credentials in OpenWork.
You do not need the old Slack bot tokens (`xoxb-...` or `xapp-...`) for this flow.
## Before you start
You need:
- A Slack workspace where you can install or request approval for Slack apps.
- A Slack app that is published in the Slack Marketplace or marked as an internal app.
- A Slack OAuth client ID and client secret from that app.
- The Slack MCP server URL: `https://mcp.slack.com/mcp`.
Keep the client secret out of chats and source control. Treat it like any other workspace secret.
## Create or approve the Slack app
In Slack, an admin should create or approve an app for OpenWork's MCP access.
1. Open [Slack API apps](https://api.slack.com/apps) and create a new app, or open the existing internal app you want to use.
2. Go to `OAuth & Permissions`.
3. Add this redirect URL: `http://127.0.0.1:19876/mcp/oauth/callback`.
4. Add the `User Token Scopes` for the Slack MCP tools your team wants OpenWork to use.
5. Save the app and install or approve it for the workspace.
6. Go to `Basic Information` > `App Credentials` and copy the `Client ID` and `Client Secret`.
Slack MCP uses user token scopes. Choose the smallest set that matches what your team wants agents to do.
For a useful read-first setup, start with:
```text
search:read.public search:read.private search:read.mpim search:read.im search:read.files search:read.users channels:history groups:history mpim:history im:history users:read users:read.email channels:read groups:read mpim:read
```
Add write scopes only if you want agents to take action in Slack:
```text
chat:write reactions:write channels:write groups:write im:write mpim:write canvases:read canvases:write
```
Use this table to pick scopes by capability:
| Slack MCP capability | User token scopes |
| --- | --- |
| Search public and private messages/channels | `search:read.public`, `search:read.private`, `search:read.mpim`, `search:read.im` |
| Search files | `search:read.files` |
| Read files | `files:read` |
| Search emoji | `emoji:read` |
| Search users | `search:read.users` |
| Send messages | `chat:write` |
| Read channels and threads | `channels:history`, `groups:history`, `mpim:history`, `im:history` |
| Create conversations/channels | `channels:write`, `groups:write`, `im:write`, `mpim:write` |
| Add reactions | `reactions:write` |
| Read and write canvases | `canvases:read`, `canvases:write` |
| Read user profiles and email | `users:read`, `users:read.email` |
| List channel members | `channels:read`, `groups:read`, `mpim:read` |
## Open the Library
In OpenWork, open your workspace and go to `Settings` > `Library`, expand `Advanced settings`, and click `Add workspace MCP`.
<Frame>
  ![OpenWork Library page listing skills, apps, and connections](/images/library-slack-connection.png)
</Frame>
## Add the Slack MCP server
In the `Add workspace MCP` dialog:
1. Set `App name` to `slack`.
2. Keep `Type` set to `Remote server (URL)`.
3. Set `Server URL` to `https://mcp.slack.com/mcp`.
4. Open `OAuth on this device`.
5. Paste the Slack OAuth client ID.
6. Paste the Slack OAuth client secret.
7. Paste the same user token scopes you added in Slack, separated by spaces.
8. Click `Add App`.
<Frame>
  ![Add workspace MCP dialog filled in for Slack with OAuth on this device expanded](/images/slack-mcp-advanced-oauth.png)
</Frame>
OpenWork writes the MCP entry with the OAuth client credentials, similar to this:
```json
{
  "mcp": {
    "slack": {
      "type": "remote",
      "enabled": true,
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "your-slack-client-id",
        "clientSecret": "your-slack-client-secret"
      }
    }
  }
}
```
If you entered scopes, OpenWork also saves them as `oauth.scope`. This is the scope list Slack sees during OAuth consent.
## Sign in to Slack
After the MCP app is added, reload the engine if OpenWork asks you to. Then start Slack MCP sign-in from the Slack app card or the MCP auth prompt.
Slack opens in your browser and shows the scopes you configured. Approve the Slack app for the workspace you want OpenWork to use, then return to OpenWork when authorization finishes.
## Troubleshooting
If you see an error like `Incompatible auth server: does not support dynamic client registration`, the Slack MCP entry is missing a pre-registered OAuth client ID and client secret. Reopen the Slack MCP setup, add those values under `Advanced OAuth`, reload the engine, and try sign-in again.
If Slack says the redirect URL is invalid, add `http://127.0.0.1:19876/mcp/oauth/callback` to the Slack app's `OAuth & Permissions` redirect URLs.
If Slack says a scope is invalid or unavailable, remove that scope from both the Slack app and OpenWork's `OAuth scopes` field, then retry. Slack workspace policies and plan settings can limit which scopes an app may request.
If your Slack workspace blocks app installation, ask a Slack admin to approve the app first. OpenWork cannot bypass Slack workspace approval policies.
@@ -0,0 +1,10 @@
---
title: "Enable Exa search"
---
[Exa](https://exa.ai) is a very fast search engine for AI. We support it as part of a global setting that is currently in  `Settings` -> `Advanced`.
<Frame>
  ![Enable Exa web search toggle in Settings > Advanced](/images/exa-search-toggle.png)
</Frame>
@@ -0,0 +1,43 @@
---
title: "OpenWork vs OpenCode models"
description: "Understand the difference between OpenWork inference and OpenCode Go or Zen models"
---
OpenWork and OpenCode are different model providers. A subscription or API key for one does not automatically give access to the other.
| Provider | Where to manage it | What it controls |
| --- | --- | --- |
| OpenWork inference | [OpenWork inference dashboard](https://app.openworklabs.com/dashboard/inference) | OpenWork-managed model access and organization usage limits |
| OpenCode Go / Zen | [OpenCode Go](https://opencode.ai/go) and [OpenCode auth](https://opencode.ai/auth) | OpenCode-managed models, subscription, and API access |
## How to tell whether you are subscribed to OpenWork inference
Open the [OpenWork inference dashboard](https://app.openworklabs.com/dashboard/inference).
- If the page shows `Subscribe`, you are not subscribed to OpenWork inference.
- If the page shows usage limits and usage remaining, you are subscribed to OpenWork inference.
<Frame>
  ![OpenWork inference usage limits](/images/openwork-inference-usage-limits.png)
</Frame>
## How OpenWork usage buckets work
OpenWork inference usage is tracked with separate usage buckets. You may see buckets such as:
- `5 hour usage limit` — a short-term bucket that resets during the day.
- `Weekly usage limit` — a weekly bucket that resets on the listed date.
- `Monthly usage limit` — a monthly bucket that resets on the listed date.
The dashboard shows how much remains in each bucket and when each bucket resets. Usage is shared across your whole OpenWork organization, not just your personal desktop app.
Organization limits scale with the number of active members in the org. For example, adding active members increases the shared organization allowance, and usage by any member draws from the same shared buckets.
## If you meant to use OpenCode models
Connect the `OpenCode Go` provider in OpenWork Desktop instead of using OpenWork inference. Follow [Using OpenCode Zen & Go Models](/start-here/connect-your-stack/using-opencode-zen-go-models) to add the provider.
Use these OpenCode links to manage that account:
- [opencode.ai/go](https://opencode.ai/go)
- [opencode.ai/auth](https://opencode.ai/auth)
@@ -0,0 +1,34 @@
---
title: "Sign in with ChatGPT"
description: "Use ChatGPT OAuth as a local model provider in OpenWork"
---
<Note>
**Local provider setup.** This connects ChatGPT directly to the desktop app. OpenWork remains free, and you do not need to sign in to OpenWork Cloud. For model access managed by your organization, see [Adding a managed LLM provider](/cloud/share-with-your-team/managed-llm-provider).
</Note>
Connecting ChatGPT with OpenWork takes four clicks.
- Go to `Settings` \> `Connect Provider` \> `OpenAI` \> `ChatGPT Pro/Plus`
<Frame>
  ![Settings page showing Connect Provider button](/images/chatgpt-connect-provider-settings.png)
</Frame>
Then sign in to OpenAI with the email for your valid subscription.
<Frame>
  ![OpenAI authentication login page](/images/chatgpt-openai-auth-login.png)
</Frame>
Once you have finished the auth, you can change the model below in the chat.
<Frame>
  ![Model selector dropdown in chat](/images/chatgpt-model-selector.png)
</Frame>
You will be able to choose among any model offered by all the providers you're connected to:
<Frame>
  ![Model list showing available models from all providers](/images/chatgpt-model-list.png)
</Frame>
@@ -0,0 +1,34 @@
---
title: "Using OpenCode Zen & Go Models"
description: "Connect your OpenCode Go provider to OpenWork Desktop"
---
OpenCode Zen and OpenCode Go models are provided by OpenCode, not OpenWork. If you have an OpenCode subscription or API key, connect the `OpenCode Go` provider in the OpenWork desktop app.
<Note>
OpenCode and OpenWork model subscriptions are separate. If you are unsure which one you have, see [OpenWork vs OpenCode models](/start-here/connect-your-stack/openwork-vs-opencode-models).
</Note>
## Connect OpenCode Go in OpenWork Desktop
1. Open OpenWork Desktop.
2. Click your avatar in the bottom-left corner.
3. Open `Settings`.
4. Go to `AI Providers`.
5. Click `Connect`.
6. Search for `opencode`.
7. Choose `OpenCode Go`.
8. Click `Connect` and enter your OpenCode API key when prompted.
<Frame>
  ![OpenCode Go provider in the Connect providers dialog](/images/opencode-go-connect-provider.png)
</Frame>
After the provider is connected, choose an OpenCode model from the model picker in a chat.
## Manage your OpenCode account
- Learn about OpenCode Go at [opencode.ai/go](https://opencode.ai/go).
- Manage your OpenCode account or authentication at [opencode.ai/auth](https://opencode.ai/auth).
If OpenWork says the OpenCode key is invalid or the model is unavailable, check your OpenCode account first. OpenWork does not manage OpenCode Go or OpenCode Zen billing.