天天AI
教程 登录
注册

首页 / 教程

OpenCode + oh-my-opencode: step-by-step install

Install OpenCode and the oh-my-openagent plugin, configure models and roles, and save tokens with Tiantian AI.

Want to write code with AI in the terminal, not just one-shot Q&A?

Try this combo:

  • OpenCode = the base (terminal AI coding agent)
  • oh-my-opencode = the plugin (multi-role orchestration: plan, execute, split work)

After install, talk to the default Sisyphus most of the time: it plans, calls helpers, and finishes the job. Role picking and ulw are in section 4.

About the links in this article: We include official / GitHub links for deeper reading, config tweaks, or later reference. Following the steps here is usually enough; you do not need to open every link.

Note: the project was renamed oh-my-openagent; people still search “oh-my-opencode”. Install commands follow the official site; both old and new package names are spelled out.

1. What each piece is

1) OpenCode

An open-source terminal AI coding agent. Desktop / IDE extensions exist; we recommend the CLI.

Docs: https://opencode.ai/docs/

2) oh-my-opencode (now oh-my-openagent)

A multi-agent orchestration plugin on top of OpenCode: a lead orchestrator plus specialist roles.

Why both? OpenCode makes an agent runnable; the plugin adds lead orchestration and specialists (Sisyphus delegates to Oracle / Librarian / Explore, etc.). The base alone can chat; for multi-role orchestration and ulw, install the plugin.

2. Install

Run this in a terminal:

node -v

If you get a version → Case 1. If the command is missing → Case 2.
Either path can get you fully installed; pick the one that matches your machine.

Case 1: You already have Node.js (npm path)

If you want this path but Node is missing: download LTS from https://nodejs.org/, install, open a new terminal, and confirm node -v / npm -v.

① Install Bun with npm

npm install -g bun

Confirm: bun -v

② Install OpenCode

npm install -g opencode-ai

Confirm: opencode --version
(Official script is equivalent: curl -fsSL https://opencode.ai/install | bash.)

③ Install the plugin

bunx oh-my-openagent install

Case 2: No Node.js (install Bun directly)

① Install Bun (site: https://bun.sh/)

macOS / Linux:

curl -fsSL https://bun.com/install | bash

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1|iex"

Confirm: bun -v

② Install OpenCode

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

Confirm: opencode --version
On Windows, WSL is recommended: https://opencode.ai/docs/windows-wsl/

③ Install the plugin

bunx oh-my-openagent install

Official plugin install notes: https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

3. Configure (smallest working loop)

The goal is simple: let OpenCode reach a model and start working.
The official “sign in to Anthropic / OpenAI subscriptions” path is expensive and roundabout. Skip it as a beginner. This guide wires Tiantian AI in one shot.

About official login
OpenCode’s “Configure” docs say the default is to type /connect, pick a provider, and enter an API key / sign in (see https://opencode.ai/docs/).
Until that is done, the UI may show Connect a provider.

We do not use that path. Write Tiantian AI into config files as below. Do not /connect to Claude / ChatGPT.

Do this instead:

  1. Write both configs first (OpenCode + plugin)
  2. Then start opencode
  3. Type /models and pick Tiantian AI

In short: official default is /connect; we write files and skip official login.

1. Get a Tiantian AI key

  1. Open https://ai.ttshuli.com, sign up, and sign in
  2. In the console, create an API key (usually looks like sk-mt-...)
  3. Copy and keep it — you will paste it into the config. Do not post it in chats or screenshots.

2. Write two config files (OpenCode + plugin)

Both live here (create the directory if missing):

  • macOS / Linux: ~/.config/opencode/
  • Windows: C:\Users\YourUsername\.config\opencode\

① OpenCode: opencode.jsonc

Prefer .jsonc (comments allowed; .json still works).

Here is a “minimal” skeleton — Tiantian AI only, plus the plugin. It is incomplete; see the pitfalls below. A full working file follows.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-openagent@latest"],
  "model": "tiantian/auto",
  "enabled_providers": ["tiantian"],
  "provider": {
    "tiantian": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Tiantian AI",
      "options": {
        "baseURL": "https://ai.ttshuli.com/v1",
        "apiKey": "replace-with-your-key"
      },
      "models": {
        "auto": {
          "name": "auto (recommended)",
          "reasoning": true,
          "limit": { "context": 180000, "output": 32000 },
          "interleaved": { "field": "reasoning_content" },
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "options": { "reasoningEffort": "medium" },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        }
      }
    }
  }
}

Full config

That minimal file often hits four snags once oh-my-openagent is on:

  1. Sub-agent models do not match.
    You can comment out "plugin" to compare: without the plugin, the skeleton can chat; with the plugin, a task may fail halfway because some sub-agents still use other software’s default models you cannot reach.

  2. No read-only role.
    With the plugin, common roles can edit files. Sometimes you only want to ask questions and touch nothing — you need a read-only role (deny edit / bash).

  3. Missing reasoning flags (especially on OpenCode 1.19).
    Custom providers do not inherit the official catalog marks. If the model entry only has "name", the UI shows No reasoning and plugin orchestration barely works.
    - Required: "interleaved": { "field": "reasoning_content" } (parse upstream reasoning stream)
    - Required: "variants" (1.19 TUI treats variants.length > 0 as “has reasoning”; "reasoning": true alone is not enough)
    - If you set "limit", both "context" and "output" are required; one without the other fails schema checks. Omit the whole object to fall back to 180000 / 32000. This platform advertises a max context of context: 180000; OpenCode uses that for auto-compaction and does not read the window from /v1/models.
    - Recommended: "options": { "reasoningEffort": "medium" } (applies effort even when no variant is selected)

  4. Image attachments need both a capability declaration and a platform route.
    OpenCode treats custom models as text-only by default. If auto does not declare image input, requests containing screenshots are rejected locally. auto should declare "modalities": { "input": ["text", "image"], "output": ["text"] }. If you still see No available auto route covers required modalities: ['image', 'text'] after adding it, the request reached Tiantian AI, but the platform currently has no enabled, available auto route covering text+image. Check that the route is enabled, not marked unavailable, and its capability list includes image. Only declare capabilities that an explicit model actually supports.

Use this full opencode.jsonc instead (replace apiKey; add/remove models from the console list as needed):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-openagent@latest"],
  "model": "tiantian/auto",
  "small_model": "tiantian/auto",
  "enabled_providers": ["tiantian"],
  "lsp": true,
  "agent": {
    "build": { "model": "tiantian/auto" },
    "plan": { "model": "tiantian/auto" },
    "general": { "model": "tiantian/auto" },
    "explore": { "model": "tiantian/auto" },
    "title": { "model": "tiantian/auto" },
    "summary": { "model": "tiantian/auto" },
    "compaction": { "model": "tiantian/auto" },
    "Sisyphus-Junior": { "model": "tiantian/auto" },
    "oracle": { "model": "tiantian/auto" },
    "librarian": { "model": "tiantian/auto" },
    "multimodal-looker": { "model": "tiantian/auto" },
    "readonly": {
      "model": "tiantian/auto",
      "mode": "primary",
      "description": "Read-only analysis",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  },
  "provider": {
    "tiantian": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Tiantian AI",
      "options": {
        "baseURL": "https://ai.ttshuli.com/v1",
        "apiKey": "replace-with-your-key"
      },
      "models": {
        "auto": {
          "name": "auto",
          "reasoning": true,
          "limit": { "context": 180000, "output": 32000 },
          "interleaved": { "field": "reasoning_content" },
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          // Also send effort when no variant is selected; long sessions sometimes return the literal "No reasoning available."
          "options": { "reasoningEffort": "medium" },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        }
      }
    }
  }
}

Notes:

  • In agent, point common roles at tiantian/auto, plus a readonly role that only answers. Press Tab to switch to it for read-only work.
  • models is what /models shows. Update it from Tiantian AI’s current list. Day to day, pick auto and let the system choose.
  • Do not omit interleaved + variants: 1.19 uses variants to show reasoning support; without them you get No reasoning and plugin orchestration is effectively broken.
  • Write limit as a pair: "limit": { "context": 180000, "output": 32000 }. context alone fails schema validation.
  • Declare image support on auto: "modalities": { "input": ["text", "image"], "output": ["text"] }. Without it, OpenCode may reject image requests locally. If you still see No available auto route covers required modalities: ['image', 'text'] after adding it, the request reached the platform; verify that an enabled, available auto route supports images (for example, nemotron-3.5-super-vl).

② Plugin: oh-my-openagent.json

The file above is not enough. Which model Sisyphus / Prometheus / Atlas (and others) use lives in the plugin config. Without it, roles often look for official default models and fail.

Create oh-my-openagent.json in the same directory:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": { "model": "tiantian/auto" },
    "hephaestus": { "model": "tiantian/auto" },
    "oracle": { "model": "tiantian/auto" },
    "explore": { "model": "tiantian/auto" },
    "librarian": { "model": "tiantian/auto" },
    "multimodal-looker": { "model": "tiantian/auto" },
    "prometheus": { "model": "tiantian/auto" },
    "metis": { "model": "tiantian/auto" },
    "momus": { "model": "tiantian/auto" },
    "atlas": { "model": "tiantian/auto" },
    "sisyphus-junior": { "model": "tiantian/auto" }
  },
  "categories": {
    "visual-engineering": { "model": "tiantian/auto" },
    "ultrabrain": { "model": "tiantian/auto" },
    "deep": { "model": "tiantian/auto" },
    "artistry": { "model": "tiantian/auto" },
    "quick": { "model": "tiantian/auto" },
    "unspecified-low": { "model": "tiantian/auto" },
    "unspecified-high": { "model": "tiantian/auto" },
    "writing": { "model": "tiantian/auto" }
  }
}

This points every plugin role / task category at tiantian/auto.

Save both files. Model names follow the console; if unsure, use auto.
(If the installer created the old name oh-my-opencode.json, apply the same contents.)

3. Open OpenCode and pick a model

Go to your project and start:

cd /path/to/your/project
opencode

Then type:

/models

Pick Tiantian AI → auto (or another name from your console). After that, talk to it normally.

(Optional) To help OpenCode understand the repo, type /init to generate AGENTS.md. Commit it if you have one; skipping it is fine for a first try.

4. How to use it (roles + common commands)

You will mainly meet three roles. The first is enough for daily work; the other two are for “write a plan first, then execute.”

Switching roles: press Tab

After OpenCode opens, the bottom of the UI shows who you are talking to.

Press Tab repeatedly to cycle:

Sisyphus → Prometheus → Atlas → back to Sisyphus…

Check the name before you speak. The wrong role does the wrong job.

What the three roles do

  1. Sisyphus — default, daily chat
    This is the default on launch. You describe the need; it plans, calls specialists, and finishes.
    Small edits and everyday coding: stay on Sisyphus. Do not switch.

  2. Prometheus — plans only, does not edit code
    Use for large or risky work when you want the scope written down first.
    Tab to it, tell it the goal; after clarifying, it writes a plan under .omo/plans/.

  3. Atlas — the executor that implements the plan
    Only after the plan exists and you agree.
    Do not chat with it casually.

How to start work after a plan exists

Two equivalent paths: both tell Atlas to execute the plan.

A (recommended, less typing) — type:

/start-work

It looks under .omo/plans/; if there are several, it asks which one, then starts.

B — Tab to Atlas, then say something like:

Execute the plan

or:

Run the plan we just wrote

Remember: after switching to Atlas you must say “execute / start”; switching alone does nothing.
/start-work skips “switch then shout” and does the same thing.

Full sequence:

  1. Tab to Prometheus → write the plan
  2. Review it yourself
  3. /start-work, or Tab to Atlas and say “execute the plan”

How to choose (one table)

You want Do this
Small change / daily work Stay on Sisyphus, just talk
Complex, and you do not want to spell out all context Stay on Sisyphus, add ulw in the prompt
Plan first, then code Tab → Prometheus writes a plan → confirm → /start-work (or Tab to Atlas and say “execute the plan”)

Prometheus / Atlas are not required every time — only when you want a written plan.

How to use ulw (examples)

ulw is short for ultrawork: adding either word to the prompt turns on a high-autonomy mode — read code, plan, implement, and check, with fewer questions.

Use it when the job is not tiny, but you do not want to list background, files, and constraints line by line.

Example — type in the chat:

ulw add nickname search and pagination on the user list page, reuse the existing table component, do not change the API contract

or:

ultrawork fix login timeout not redirecting back to the login page

Do not turn on ulw for tiny tasks; telling Sisyphus exactly what to change is cheaper.

How to use /ulw-loop

/ulw-loop is the longer-running variant: split a large goal into steps, advance against the goal, keep checkpoints, and treat verifiable results as done.
More systematic than a one-shot ulw; good for multi-file, staged work that might stall halfway.

Usage: slash command plus your goal, for example:

/ulw-loop change signup to phone + verification code, keep old email signup compatible, finish and verify the critical path

Rough split vs ulw:

  • ulw: drop a phrase in the prompt and go (short/medium tasks)
  • /ulw-loop: loop split / check / continue against a large goal (long tasks / milestones)

Beginners can start with “talk to Sisyphus” and occasional ulw; later try /ulw-loop and “Tab to Prometheus → /start-work”.

Other roles (usually auto-delegated)

Sisyphus typically assigns them: Oracle (architecture), Librarian (docs / open-source), Explore (code search), Hephaestus (deeper execution), etc. Official docs have the full list.

Orchestration: https://github.com/code-yeongyu/oh-my-openagent/blob/HEAD/docs/guide/orchestration.md
README: https://github.com/code-yeongyu/oh-my-openagent

OpenCode extras

Docs: https://opencode.ai/docs/

  • opencode → enter the current project
  • opencode --auto enter the current project and auto-approve permissions when you do not want to confirm every step
  • opencode --auto -c same, and continue the last session
  • /init → generate AGENTS.md
  • Tab → switch the current role (Sisyphus / Prometheus / Atlas, etc.)
  • /undo / /redo → undo / redo
  • @filename → add to context

Plugin shortcuts

  • ultrawork or ulw → keyword in the prompt for high autonomy
  • /ulw-loop <goal> → loop split and advance against a large goal
  • /start-work → start from a plan (same as “Tab to Atlas + say execute”, with less typing)

5. Tokens are expensive — what now?

You already connected Tiantian AI, which is usually cheaper than official subscriptions. Three more habits:

  1. Do not turn on ultrawork / /ulw-loop for small jobs; tell Sisyphus exactly what to change
  2. For genuinely complex work that you fear redoing, plan first then /start-work
  3. Pick the right model: do not use the most expensive tier for simple work; prefer auto and let the server choose

Lost or rotating a key: create a new one in the https://ai.ttshuli.com console and update apiKey in opencode.jsonc. If you change model names, update tiantian/auto in both opencode.jsonc and oh-my-openagent.json.

Official links

First run: write opencode.jsonc + oh-my-openagent.json → opencode → /models pick Tiantian AI → give Sisyphus a small task; try ulw when it is harder; for a written plan: Tab to Prometheus → confirm → /start-work.