opencode-map
中文
← guides/

Getting started with opencode

BeginnerLast updated: Oct 21, 2026

opencode is an open-source AI coding agent. It runs as a terminal interface (TUI), a desktop app, or an IDE extension. This guide covers the terminal path: install, connect a provider, initialize a project, and ship your first change.

Install

This guide covers OpenCode 1, the stable line documented at opencode.ai/docs. OpenCode 2 is now available (v2 docs) — both use the opencode binary name and cannot be installed side by side, so installing v1 with the methods below can conflict with or replace a v2 install.

The recommended install is the official script:

curl -fsSL https://opencode.ai/install | bash

Package-manager alternatives:

npm install -g opencode-ai        # Node.js (also bun / pnpm / yarn)
brew install anomalyco/tap/opencode  # macOS/Linux — the Anomaly tap tracks releases fastest
sudo pacman -S opencode           # Arch Linux (stable); paru -S opencode-bin tracks AUR
choco install opencode            # Windows (WSL recommended); scoop install opencode also works
mise use -g github:anomalyco/opencode  # mise
docker run -it --rm ghcr.io/anomalyco/opencode  # container

On Windows the docs recommend WSL for full feature compatibility. You can also grab binaries straight from GitHub Releases.

Connect a provider

opencode is provider-agnostic — it supports 75+ providers via models.dev, so you bring your own API keys. If you don’t have provider accounts, OpenCode Zen is the team’s curated, tested model list billed per-request through an opencode account — or look at OpenCode Go, the team’s flat subscription option.

Inside the TUI run:

/connect

Pick a provider (opencode/Zen, Anthropic, OpenAI, …), follow the auth flow, and paste the API key when prompted.

Initialize a project

cd /path/to/project
opencode

Then run:

/init

opencode analyzes the project and writes an AGENTS.md at the root describing structure and conventions. Commit it — it improves every future session.

The plan/build workflow

The TUI has two modes, toggled with Tab:

  • Build mode (default) — opencode makes changes directly.
  • Plan mode — read-only; it proposes a plan you can iterate on before switching back to build.

A reliable first-feature loop:

  1. Tab into plan mode, describe the feature with as much context as you can (drag-and-drop images works).
  2. Iterate on the plan until it looks right.
  3. Tab back to build mode: “Go ahead and make the changes.”

Use @ to fuzzy-reference files in prompts: How is auth handled in @src/api/index.ts.

Undo, redo

  • /undo reverts the last change and restores your message; run repeatedly to step back further. Undo requires the project to be a Git repository.
  • /redo re-applies it.

Further reading