# OpenCode Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (OpenCode v1.18.31, released 2026-09-14 (repo now anomalyco/opencode))

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (anthropic provider) · GPT ✅ · Chinese models ✅ (openai provider) · Gemini ✅ (google provider) |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/claude/v1` · OpenAI: `https://api.qcode.cc/openai/v1` · Gemini: `https://api.qcode.cc/gemini/v1beta` (per-provider `options.baseURL`) |
| Where to configure | `~/.config/opencode/opencode.json`; keys via `opencode auth login` into `auth.json` |
| Official docs | [opencode.ai/docs](https://opencode.ai/docs) |

> ⚠️ **Important: API Direct Access Permission Required**
>
> Using OpenCode requires enabling API direct access permission. Since direct API calls don't have Claude Code's session mechanism, token consumption will be higher, so this permission is **disabled by default**.
>
> To enable it, please contact our online support or email **hi@qcode.cc**, and we'll activate this permission for your purchased API Key.

[OpenCode](https://github.com/anomalyco/opencode) is a 100% open-source terminal AI coding assistant, similar to Claude Code but with more flexibility and customization options. It supports multi-model switching, LSP integration, TUI interface, and is not tied to any specific AI provider.

## Project Introduction

### OpenCode

[OpenCode](https://github.com/anomalyco/opencode) is an open-source AI coding agent developed by the SST team. Key features include:

- **100% Open Source** - MIT license, fully transparent

- **Multi-Model Support** - Use Claude, OpenAI, Google Gemini, and more simultaneously

- **Native LSP Support** - Built-in Language Server Protocol for intelligent code analysis

- **TUI First** - Designed for terminal users, built by Neovim enthusiasts

- **Client/Server Architecture** - Run the server locally and control remotely from mobile devices

- **Dual Built-in Agents** - `build` (default, full access) and `plan` (read-only, for analysis and planning)

**Project Stats** (as of January 2026):

- GitHub Stars: 208k+ (as of 2026-09)

- Repository: `anomalyco/opencode` (formerly `sst/opencode`; old URL redirects)

- Version: v1.18.31 (released 2026-09-14)

### oh-my-opencode

[oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) is an enhancement plugin for OpenCode, often called "OpenCode on steroids", providing a professional-grade AI coding experience:

**Core Features**:

- **Async Subagents** - Parallel task processing capability similar to Claude Code

- **Curated Agent Configurations** - Pre-configured professional agent roles (Oracle, Librarian, Explore, etc.)

- **LSP/AST Tools** - Intelligent refactoring, code analysis, symbol search, and more

- **Claude Code Compatibility Layer** - Supports Claude Code hooks, commands, and skills configurations

- **Sisyphus Main Agent** - Powerful orchestration agent based on Claude Opus 4.8 with background parallel tasks

- **ultrawork Mode** - Just add `ultrawork` to your prompt to enable the most powerful parallel orchestration mode

**Built-in Agent Roles**:

| Agent Name | Model | Purpose |
|------------|-------|---------|
| **Sisyphus** | Claude Opus 4.8 | Main orchestrator, plans and delegates tasks |
| **Oracle** | GPT 5.4 | Architecture design, code review, strategy analysis |
| **Librarian** | Claude Sonnet 4.6 | Multi-repo analysis, doc lookup, implementation examples |
| **Explore** | Grok Code | Fast codebase exploration and pattern matching |
| **Frontend UI/UX** | Gemini 2.5 Pro | Frontend development, excels at creating beautiful UIs |

## Installation & Configuration

### Step 1: Install OpenCode

OpenCode iterates rapidly, please refer to the official installation guide:

**Official Documentation**: [https://opencode.ai/docs](https://opencode.ai/docs)

Common installation methods:

```bash
# Install with curl (recommended)
curl -fsSL https://opencode.ai/install | bash

# Using package managers
npm install -g opencode-ai  # or bun/pnpm/yarn

# macOS Homebrew
brew install anomalyco/tap/opencode
```

### Step 2: Install oh-my-opencode (Recommended)

oh-my-opencode provides professional out-of-the-box configurations, highly recommended:

```bash
bunx oh-my-opencode install
```

**Official Documentation**: [https://github.com/code-yeongyu/oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)

> **Tip**: During installation, you'll be asked which AI subscriptions you have (Claude, ChatGPT, Gemini). Select based on your actual subscriptions.

### Step 3: Configure QCode API

This is the key step! Create or edit the configuration file `~/.config/opencode/opencode.json`:

> **About Model Selection**: The configuration below uses QCode's Claude 5 line and GPT Codex models. Daily defaults are `claude-sonnet-5` / `claude-opus-5`; 4.x is still on sale. QCode **does sell Gemini** (see [qcode.cc/models](https://qcode.cc/models)) and **does not sell grok**. China-family ids: [China-family models](/docs/usage/cn-models).

> **About the Google Provider Block**: The `google` provider block in the configuration is used to connect to Gemini (e.g. `gemini-2.5-pro`, `gemini-3.5-flash`). Note: the official Gemini CLI Pro/free tiers reached end of life on 2026-06-18 ([Google announcement](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)); the successor is **Google Antigravity CLI**. Enterprise paid keys are unaffected. If you need a Google model toolchain, we recommend switching to the Antigravity CLI.

```json
{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qcode.cc/claude/v1"
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.qcode.cc/openai"
      }
    },
    "google": {
      "options": {
        "baseURL": "https://api.qcode.cc/gemini/v1beta"
      }
    }
  },

  "model": "anthropic/claude-opus-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "default_agent": "build",

  "permission": {
    "read": "allow",
    "list": "allow",
    "glob": "allow",
    "grep": "allow",
    "lsp": "allow",

    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask",
    "websearch": "ask",

    "external_directory": "deny",
    "doom_loop": "ask"
  },

  "agent": {
    "plan": {
      "mode": "primary",
      "description": "Planning/decomposition/technical design (read-only, avoid accidental code changes)",
      "model": "anthropic/claude-opus-5",
      "temperature": 0.1,
      "prompt": "You are a senior technical lead. Goal: break down requirements into executable steps (with acceptance criteria/risks/rollback). Read-only by default, do not modify files or run commands; if execution is truly needed, explain the reason and suggest switching to build/codex.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "build": {
      "mode": "primary",
      "description": "Main development (end-to-end implementation/debugging/fixing tests) - Claude Opus 5",
      "model": "anthropic/claude-opus-5",
      "temperature": 0.2,
      "prompt": "You are the main software engineering agent. Priorities: minimal viable changes, readability, testability. Before making changes, briefly explain the approach; after changes, always provide: key diff points, how to verify locally (commands), potential edge cases.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "allow",
        "bash": "allow",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "ask"
      }
    },

    "codex": {
      "mode": "primary",
      "description": "Refactoring/migration/major changes (Codex) - GPT-5.4",
      "model": "openai/gpt-5.4",
      "temperature": 0.2,
      "prompt": "You are a Codex-style engineering agent, skilled in large-scale refactoring, migration, code review, and complex toolchain collaboration. Priority: keep the project runnable: step-by-step commits, each step verifiable; when uncertain, add safeguards and tests first.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "allow",
        "bash": "allow",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "ask"
      }
    },

    "review": {
      "mode": "subagent",
      "description": "Code review/second brain (read-only) - GPT-5.3-Codex",
      "model": "openai/gpt-5.6-terra",
      "temperature": 0.1,
      "prompt": "You are a strict code reviewer. Output: 1) Key risks (bugs/security/concurrency/edge cases) 2) Maintainability suggestions 3) Minimal modification suggestions (can use pseudo diff) 4) Necessary test points. Read-only by default, do not modify files/run commands.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "explore": {
      "mode": "subagent",
      "description": "Quick code scan/file location/context summary (read-only) - Claude Haiku 4.5",
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.1,
      "prompt": "You are a quick exploration subagent: locate relevant files/functions/call chains with minimal steps, provide clear paths and summaries. Read-only by default, do not modify files/run commands.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "general": {
      "mode": "subagent",
      "description": "General research/documentation/comparing approaches (medium cost) - Claude Sonnet 5",
      "model": "anthropic/claude-sonnet-5",
      "temperature": 0.2,
      "prompt": "You are a general analysis subagent: focus on explanation, trade-offs, documentation, and approach comparison; read-only by default, try not to modify code.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "think": {
      "mode": "subagent",
      "description": "Assist thinking/edge case reasoning (read-only) - GPT-5.4-Mini",
      "model": "openai/gpt-5.6-mini",
      "temperature": 0.2,
      "prompt": "You are a reasoning and edge case analysis subagent: provide structured analysis and suggestions for design, exception paths, concurrency/consistency, performance bottlenecks. Read-only by default.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    }
  }
}
```

#### API Endpoint Selection

Based on your network situation, you can modify the `baseURL` in the `provider` configuration:

| Endpoint | Anthropic (Claude) | OpenAI (Codex) | Use Case |
|----------|-------------------|----------------|----------|
| **Domain** (Recommended) | `https://api.qcode.cc/claude/v1` | `https://api.qcode.cc/openai` | Global users, auto-selects optimal node |

> **For China Mainland Users**: For best performance, change `baseURL` to `https://api.qcode.cc/claude/v1` and `https://api.qcode.cc/openai`.

#### Available Models

QCode currently supports these popular models:

**Claude Series** (path: `/claude/v1`):

- `claude-opus-5` - current flagship (`claude-opus-4-8` still on sale)

- `claude-sonnet-5` - daily default (`claude-sonnet-4-6` still on sale)

- `claude-haiku-4-5` - Haiku 4.5, ultra-fast response

**OpenAI/Codex Series** (path: `/openai`):

- `gpt-5.6-terra` - Programming / Codex CLI (recommended)

- `gpt-5.6-sol` / `gpt-5.6-luna` - 5.6 siblings

- `gpt-5.5` / `gpt-5.4` - previous gen, still usable

- `gpt-5.6-mini` - Lightweight / cost-effective

#### Configuration Overview

The above configuration includes a complete multi-agent workflow:

| Agent | Model | Mode | Purpose |
|-------|-------|------|---------|
| **plan** | Claude Opus 5 | primary | Planning/decomposition/technical design (read-only) |
| **build** | Claude Opus 5 | primary | Main development, end-to-end implementation |
| **codex** | GPT-5.4 | primary | Refactoring/migration/major changes |
| **review** | GPT-5.3-Codex | subagent | Code review (read-only) |
| **explore** | Claude Haiku 4.5 | subagent | Quick code scan/file location (read-only) |
| **general** | Claude Sonnet 5 | subagent | General research/documentation (read-only) |
| **think** | GPT-5.4-Mini | subagent | Assist thinking/edge case reasoning (read-only) |

You can customize each agent's `model`, `prompt`, and `permission` settings according to your preferences.

### Step 4: Configure API Key

After opening OpenCode, use the `/connect` command to configure your API Key:

#### Configure Anthropic (Claude)

1. Type `/connect` in OpenCode

2. Select **Anthropic**

3. Select **Manually enter API Key**

4. Enter the API Key you purchased from QCode

5. Press Enter to save

#### Configure OpenAI (Codex)

1. Type `/connect`

2. Select **OpenAI**

3. Select **Manually enter API Key**

4. Enter the API Key you purchased from QCode

5. Press Enter to save

#### Save and Restart

After configuration:

1. Type `/exit` to exit OpenCode

2. Reopen OpenCode

Your API Keys are saved in `~/.local/share/opencode/auth.json` and can be edited directly for future adjustments.

## Verify Configuration

After reopening OpenCode, verify your configuration by testing:

```bash
# Start OpenCode
opencode

# Test in OpenCode
> Hello, please introduce yourself
```

If the conversation works normally, your configuration is successful!

## Usage Tips

### ultrawork Mode

If you have oh-my-opencode installed, just add `ultrawork` or `ulw` to your prompt to enable the most powerful parallel multi-model orchestration mode:

```text
ultrawork Help me refactor the authentication module of this project
```

### Background Tasks

Use the `@` syntax to call specialized agents for specific tasks:

```text
@oracle Review the architecture design of this code
@librarian Find similar open-source implementations
@explore Search for all API endpoints in the project
```

### Tab to Switch Agents

Press `Tab` to switch between `build` and `plan` agents:

- **build** - Full permissions, for development work

- **plan** - Read-only mode, for analysis and planning

## Troubleshooting

### API Connection Failed

1. Check if the API endpoint configuration is correct

2. Confirm the API Key is saved correctly

3. Try switching to another API endpoint (e.g., `asia.qcode.cc` / `us` / `eu` fallback)

4. Check if your network requires a proxy

### Model Not Available

Ensure the model definition is correctly configured in `opencode.json` and the model ID matches QCode's supported model names.

### oh-my-opencode Configuration Issues

Refer to the official documentation: [https://github.com/code-yeongyu/oh-my-opencode#configuration](https://github.com/code-yeongyu/oh-my-opencode#configuration)

## Related Links

- [OpenCode Official Website](https://opencode.ai)

- [OpenCode GitHub](https://github.com/anomalyco/opencode)

- [oh-my-opencode GitHub](https://github.com/code-yeongyu/oh-my-opencode)

- [OpenCode Official Documentation](https://opencode.ai/docs)

## Next Steps

- Check [VS Code Integration](/docs/ide/vscode) for IDE usage

- Explore [Codex Integration](/docs/ide/codex) to use OpenAI Codex models

- Learn [CLI Tips](/docs/usage/cli-tips) to improve terminal efficiency