OpenCode Configuration

1. Install OpenCode

1.1 macOS / Linux Installation

For macOS: Press ⌘ Command + Space, type Terminal and press Enter

For Linux: Click the application menu in the bottom left, search for Terminal and press Enter

Run the following command in Terminal to install OpenCode:

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

Verify OpenCode Installation

After installation, run the following command to verify successful installation:

opencode --version

1.2 Windows Installation

Click the "Start" button, type "powershell" in the search box, and run PowerShell as Administrator

Install using PowerShell:

irm https://opencode.ai/install.ps1 | iex

Other installation methods:

• Using Chocolatey:

  choco install opencode

• Using Scoop:

  scoop install opencode

• Using NPM:

  npm install -g opencode-ai

Verify OpenCode Installation

After installation, run the following command to verify successful installation:

opencode --version

It is recommended to use PowerShell instead of CMD for more powerful features

If you encounter permission issues, run PowerShell as Administrator

2. Configure Credentials

2.1 Configuration File Method (Recommended)

OpenCode automatically reads credentials from the configuration file on startup, no need to set environment variables.

Global Configuration (User Level)

Edit the ~/.config/opencode/opencode.json file:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "your-api-token"
    }
  },
  "model": "anthropic/claude-sonnet-4-20250514"
}

Project-Level Configuration

Create an opencode.json file in the project root directory (overrides global configuration):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "your-api-token",
      "baseUrl": {{apiUrl}}
    }
  }
}

Configuration Priority:

1. Project root ./opencode.json (Highest)
2. User home directory ~/.config/opencode/opencode.json
3. Command line parameters --api-key / --base-url (Lowest)

2.2 Environment Variable Method

macOS / Linux Configuration

Refer to section 1.1, enter Terminal, and edit your shell configuration file (depending on which shell you use):

For zsh (default):

# Add opencode environment variables to ~/.zshrc file:
echo 'export OPENCODE_API_KEY="■■API■■"' >> ~/.zshrc
echo 'export OPENCODE_BASE_URL={{apiUrl}}' >> ~/.zshrc
# Make configuration effective:
source ~/.zshrc

For bash:

# Add opencode environment variables to ~/.bash_profile
echo 'export OPENCODE_API_KEY="■■API■■"' >> ~/.bash_profile
echo 'export OPENCODE_BASE_URL={{apiUrl}}' >> ~/.bash_profile
# Make configuration effective:
source ~/.bash_profile

Windows Configuration

Run the following commands in PowerShell to set user-level environment variables:

[System.Environment]::SetEnvironmentVariable("OPENCODE_API_KEY", "■■API■■", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("OPENCODE_BASE_URL", {{apiUrl}}, [System.EnvironmentVariableTarget]::User)

Or set system environment variables directly: Right-click This PC → Properties → Advanced system settings → Environment Variables → New user variable

3. Startup Parameter Configuration

3.1 Environment Variable Method (Recommended)

# macOS / Linux
export OPENCODE_API_KEY="your-api-token"
export OPENCODE_BASE_URL={{apiUrl}}

3.2 Command Line Parameter Method

opencode --api-key "your-api-token" --base-url {{apiUrl}}

3.3 Configuration File Method

Create an opencode.json file in the project root directory:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenswitch": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenSwitch",
      "options": {
        "baseURL": {{apiUrl}},
        "apiKey": "your-api-token"
      },
      "models": {
        "model-id": {
          "name": "Model Name"
        }
      }
    }
  }
}

3.4 Complete Startup Parameter Description

Parameter	Description	Example
--api-key	API authentication token	--api-key "sk-xxx"
--base-url	Proxy API address	--base-url
--model	Specify the model to use	--model "claude-sonnet-4-20250514"
--theme	Interface theme	--theme "dark"
--no-git	Disable git integration	--no-git
--verbose	Detailed log output	--verbose

4. File Path Considerations

4.1 Configuration File Loading Path

OpenCode looks for configuration files in the following order:

1. Current project root: ./opencode.json or ./opencode.jsonc
2. User home directory: ~/.config/opencode/opencode.json

4.2 Project Description Files

OpenCode automatically reads description files in your project to understand the project context:

• AGENTS.md - Project-level instruction description (Recommended)
• CLAUDE.md - Claude Code format compatible
• README.md - Project description

It is recommended to create an AGENTS.md file in the project root directory and write project standards (e.g., always use TypeScript, test framework is Vitest, indent with 2 spaces)

4.3 MCP Server Configuration

MCP server configuration file path:

~/.config/opencode/mcp.json

Configuration example:

{
  "servers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

4.4 Working Directory

• OpenCode runs in the directory where the command is executed by default
• Use the cd command to switch to the project directory before starting OpenCode
• All file operations are based on the current working directory

5. Get Started

After installation and configuration, run opencode in the project root directory:

# Navigate to the project folder
cd your-project

# Start OpenCode
opencode

You can communicate with it directly through conversation-style commands:

• Explore codebase: opencode "Explain how the permission verification logic is implemented in this project"
• Fix bug: opencode "Fix the 500 error when user logs in, refer to the error message in logs/error.log"
• Write tests: opencode "Write unit tests for auth.service.ts and run until all tests pass"
• Automate tasks: opencode "Update all deprecated API calls to v2 version in the project and run lint to fix formatting"

6. Common Built-in Commands

In the opencode interactive interface, you can use slash commands for interaction:

6.1 Basic Commands

Command	Description
/help	Show help information
/init	Initialize project, analyze project structure and create AGENTS.md file
/connect	Connect to LLM provider (OpenAI, Anthropic, etc.)
/models	View and switch AI models
/clear	Clear current conversation context
/exit	Exit OpenCode
/quit	Exit OpenCode (same as /exit)

6.2 Session Management

Command	Description
/compact	Compress conversation history to save tokens
/history	View conversation history
/resume	Resume previous session

6.3 File Operations

Command	Description
/read <file>	Read the content of specified file
/edit <file>	Edit specified file
/write <file>	Write to file

6.4 Models and Configuration

Command	Description
/model	Switch AI model
/config	View/modify configuration
/theme	Switch interface theme

6.5 Development Assistance

Command	Description
/run <cmd>	Execute shell command
/git	Git related operations
/test	Run tests
/lint	Code linting

6.6 Plan Mode and Mode Switching

Switch to Plan Mode

Press the Tab key to enter or exit Plan Mode

• Plan Mode: OpenCode only makes a plan, does not make changes, used for planning large-scale changes
• Build Mode (default): OpenCode can make code changes

Before requesting OpenCode to make large-scale changes, first switch to Plan Mode to let it outline the plan, confirm it, then switch back to Build Mode to execute. This prevents misunderstandings from causing many invalid modifications.

7. Usage Tips

7.1 Use /clear Promptly

Don't chat too long in one session. When a task is completed, immediately type /clear. Outdated context will be repeatedly sent with every new message, causing unnecessary costs.

7.2 Leverage Project Description Files

Create an AGENTS.md file in the project root directory. Write project standards here (e.g., always use TypeScript, test framework is Vitest, indent with 2 spaces).

• Benefits: You don't need to repeat these requirements in every conversation, reducing input tokens.

7.3 Use Plan Mode Effectively

Before requesting OpenCode to make large-scale changes, press the Tab key to enter Plan Mode.

In Plan Mode, OpenCode will only make a plan without making actual changes. After confirming the plan is correct, press Tab again to switch back to Build Mode to execute. This prevents misunderstandings from causing many invalid modifications and unnecessary costs.

7.4 Use /compact to Compress Context

When the conversation gets long, use the /compact command to compress conversation history, which can reduce token consumption while maintaining context.

7.5 Multi-Model Switching

Use the /model command to switch between different AI models at any time, selecting the appropriate model based on task complexity:

• Simple tasks: Use a lighter weight model
• Complex tasks: Use a more powerful model