> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> Install OpenCode v2, sign in to a provider, choose its setup in CoClip and fix version messages.

OpenCode is an open-source command-line agent that works with the model provider you choose. In CoClip it runs in an **OpenCode** tab of the [AI dock](/docs/ai-agents/ai-dock.md), with the CoClip tools, skills and agent roles added for that session.

## Version CoClip needs

CoClip needs OpenCode **v2**: **2.1.0** or newer, below **3.0.0**.

* `opencode --version` prints `opencode v2.x` for the v2 line.
* The older v1 line uses the same `opencode` command and is refused. Install v2 to replace it.

## Install and sign in

CoClip never installs or updates OpenCode. The install commands come from the OpenCode project; check the [OpenCode v2 docs](https://opencode.ai/v2/docs) for the current steps.

**1. Install OpenCode v2**

> [tab] Windows
>
> Open PowerShell and run:
>
> ```powershell theme={null}
> npm install -g @opencode/cli
> ```

> [tab] macOS
>
> Open Terminal and run:
>
> ```bash theme={null}
> curl -fsSL https://opencode.ai/v2/install | bash
> ```

**2. Sign in to a provider once**

Run `opencode` and sign in to the model provider you want to use. Your sign-in stays on your computer.

**3. Open an OpenCode tab**

In CoClip, click **+** in the AI dock and pick **OpenCode**.

## Choose the setup

Open **Settings** → **AI assistants** → **OpenCode**:

| Option | What OpenCode loads |
| - | - |
| **CoClip setup only (recommended)** | Only CoClip's tools, skills and agents for that session. Keeps your sign-in. Your OpenCode config, MCP servers, agents, plugins and personal skills (including `~/.agents/skills`) stay off for these sessions. |
| **Use my own OpenCode setup** | Also your own configuration, with CoClip's tools, skills and agents added for that session only. |

The choice applies to the next OpenCode session the AI dock starts. CoClip never writes to your OpenCode config.

## Messages and fixes

| What you see | Fix |
| - | - |
| **OpenCode is not installed on this PC** (or Mac) | Install OpenCode v2 with the command for your system above, run `opencode` once to sign in to a provider, then click **Open OpenCode again**. |
| **This PC has OpenCode …, from the v1 line. CoClip needs OpenCode v2** | Install OpenCode v2 with the command above. It replaces the v1 `opencode` command. |
| **OpenCode … is too old for CoClip** | Install the latest OpenCode v2, then click **Open OpenCode again**. |
| **… which is newer than this version of CoClip knows** | Your OpenCode is 3.0.0 or later. Update CoClip, or install OpenCode v2 again. |
| **CoClip could not read the OpenCode version** | Run `opencode --version` in a terminal. If it fails, reinstall OpenCode v2. |
| **CoClip starts OpenCode's own opencode.exe, but only the npm launcher was found** (Windows) | Reinstall with `npm install -g @opencode/cli`, or use the **Standalone install** link the tab shows and put `opencode.exe` in a folder on your PATH. |
| **OpenCode reads "\{env:" and "\{file:" in its settings…** | Your project folder path contains `{env:` or `{file:`. Rename or move the folder so its path has neither, then open the tab again. |
| **OpenCode support is incomplete in this build of CoClip** | Reinstall CoClip. See [Install](/docs/get-started/install.md). |
| OpenCode is still not found after installing | Restart CoClip. |
| **OpenCode 1 exited** | Click **Restart** for a new session, or **Close** to drop the tab. |

## Related pages

* [Use OpenCode outside the editor](/docs/ai-agents/outside-the-editor.md#opencode)
* [AI log and undo](/docs/ai-agents/ai-log-and-undo.md)
* [Troubleshooting](/docs/reference/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.