OpenCode

https://opencode.ai/docs/zh-cn
Admin
OpenCode is an open-source AI coding agent that provides terminal interface, desktop application,...
Tokens:77,498
Snippets:965
Trust Score:8.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Attach example

Source: https://opencode.ai/docs/zh-cn/cli

Example demonstrating how to start a backend server and then attach the TUI to it.

```bash
# Start the backend server for web/mobile access
opencode web --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
opencode attach http://10.20.30.40:4096
```

--------------------------------

### Install OpenCode CLI

Source: https://opencode.ai/docs/zh-cn/github

Run this command in your GitHub repository to install OpenCode and initiate the setup process for GitHub App integration, workflow creation, and key configuration.

```bash
opencode github install
```

--------------------------------

### Installation

Source: https://opencode.ai/docs/zh-cn/sdk

Install the OpenCode AI SDK using npm.

```APIDOC
## Installation

Install the SDK from npm:

```bash
npm install @opencode-ai/sdk
```
```

--------------------------------

### Install wl-clipboard for Wayland

Source: https://opencode.ai/docs/zh-cn/troubleshooting

For Wayland systems, install 'wl-clipboard' using apt to enable clipboard functionality.

```bash
apt install -y wl-clipboard
```

--------------------------------

### Setup xvfb for Headless Environments

Source: https://opencode.ai/docs/zh-cn/troubleshooting

In headless environments, install 'xvfb' and configure the DISPLAY environment variable to enable clipboard functionality.

```bash
apt install -y xvfb
```

```bash
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0
```

--------------------------------

### Install xclip or xsel for X11

Source: https://opencode.ai/docs/zh-cn/troubleshooting

For X11 systems, install either 'xclip' or 'xsel' using apt to enable clipboard functionality.

```bash
apt install -y xclip
```

```bash
apt install -y xsel
```

--------------------------------

### Secure OpenCode Server with Password

Source: https://opencode.ai/docs/zh-cn/windows-wsl

When using `--hostname 0.0.0.0`, it is crucial to set the OPENCODE_SERVER_PASSWORD environment variable to protect your server. This example shows how to set the password and start the server.

```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0
```

--------------------------------

### Install opencode SDK

Source: https://opencode.ai/docs/zh-cn/sdk

Install the opencode SDK using npm. This command is used to add the SDK to your project's dependencies.

```bash
npm install @opencode-ai/sdk
```

--------------------------------

### Start OpenCode TUI

Source: https://opencode.ai/docs/zh-cn/tui

Launches the TUI for the current directory.

```bash
opencode
```

--------------------------------

### Install OpenCode AI via Script

Source: https://opencode.ai/docs/zh-cn

Use this command to install OpenCode AI using the provided installation script. Ensure you have curl installed.

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

--------------------------------

### JSONC Configuration Example

Source: https://opencode.ai/docs/zh-cn/config

An example of a JSONC configuration file for OpenCode, demonstrating basic settings like model, autoupdate, and server port. JSONC allows for comments, making configuration more readable.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}
```

--------------------------------

### Create a Full opencode Client

Source: https://opencode.ai/docs/zh-cn/sdk

Create an opencode instance that starts both the server and the client. This is the default way to initialize the SDK.

```javascript
import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()
```

--------------------------------

### Start Web Interface Server

Source: https://opencode.ai/docs/zh-cn/cli

Launch an OpenCode server with a web interface.

```bash
opencode web
```

--------------------------------

### Create Opencode Client

Source: https://opencode.ai/docs/zh-cn/sdk

Create an instance of the OpenCode client, which starts both the server and client.

```APIDOC
## Create Client

Create an instance of the opencode client:

```javascript
import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()
```

This starts both the server and the client.

### Options

| Option       | Type          | Description                       | Default Value | 
| ------------ | ------------- | --------------------------------- | ------------- |
| `hostname`   | `string`      | The hostname of the server        | `127.0.0.1`   |
| `port`       | `number`      | The port of the server            | `4096`        |
| `signal`     | `AbortSignal` | An abort signal to cancel operations | `undefined`   |
| `timeout`    | `number`      | Server startup timeout in ms      | `5000`        |
| `config`     | `Config`      | Configuration object              | `{}`          |
```

--------------------------------

### Prompt to Use Local MCP Tool

Source: https://opencode.ai/docs/zh-cn/mcp-servers

Example prompt demonstrating how to invoke a configured local MCP tool, `mcp_everything`, to perform an action.

```text
use the mcp_everything tool to add the number 3 and 4
```

--------------------------------

### Install OpenCode AI with Chocolatey on Windows

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI on Windows using Chocolatey. This is a convenient package manager for Windows.

```bash
choco install opencode
```

--------------------------------

### Install OpenCode AI with Bun

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI globally using Bun. This is another Node.js package manager option.

```bash
bun install -g opencode-ai
```

--------------------------------

### Install OpenCode AI with Scoop on Windows

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI on Windows using Scoop. Scoop is another popular package manager for Windows.

```bash
scoop install opencode
```

--------------------------------

### Installing opencode-helicone-session Plugin

Source: https://opencode.ai/docs/zh-cn/providers

Command to install the opencode-helicone-session npm plugin.

```bash
npm install -g opencode-helicone-session
```

--------------------------------

### TUI Configuration Example

Source: https://opencode.ai/docs/zh-cn/tui

Example configuration for tui.json to customize TUI behavior.

```json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}
```

--------------------------------

### Install OpenCode AI with Mise

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI using Mise, a polyglot version manager. This command ensures you have the latest version from GitHub.

```bash
mise use -g github:anomalyco/opencode
```

--------------------------------

### Install OpenCode AI with Yarn

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI globally using Yarn. This is another Node.js package manager option.

```bash
yarn global add opencode-ai
```

--------------------------------

### Install OpenCode AI with npm

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI globally using npm. This is one of the Node.js package manager options.

```bash
npm install -g opencode-ai
```

--------------------------------

### Install OpenCode AI on Arch Linux

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI on Arch Linux using pacman for the stable version or paru for the latest from AUR.

```bash
sudo pacman -S opencode
```

```bash
paru -S opencode-bin
```

--------------------------------

### Navigate to Project and Run OpenCode

Source: https://opencode.ai/docs/zh-cn/windows-wsl

After installing OpenCode in WSL, navigate to your project directory (mounted via /mnt/) and run the opencode command.

```bash
cd /mnt/c/Users/YourName/project
opencode
```

--------------------------------

### Serve OpenCode with External Connections

Source: https://opencode.ai/docs/zh-cn/windows-wsl

Start the OpenCode server in WSL, binding to all interfaces (0.0.0.0) to allow connections from your desktop application. Ensure a port is specified.

```bash
opencode serve --hostname 0.0.0.0 --port 4096
```

--------------------------------

### Install OpenCode AI with Homebrew

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI on macOS and Linux using Homebrew. It's recommended to use the anomalyco tap for the latest versions.

```bash
brew install anomalyco/tap/opencode
```

--------------------------------

### Install OpenCode AI with pnpm

Source: https://opencode.ai/docs/zh-cn

Install OpenCode AI globally using pnpm. This is another Node.js package manager option.

```bash
pnpm install -g opencode-ai
```

--------------------------------

### Start ACP Server

Source: https://opencode.ai/docs/zh-cn/cli

Launch the ACP (Agent Client Protocol) server.

```bash
opencode acp
```

--------------------------------

### Add `@modelcontextprotocol/server-everything` Local MCP

Source: https://opencode.ai/docs/zh-cn/mcp-servers

Example of adding the `@modelcontextprotocol/server-everything` MCP server locally. Use the `mcp_everything` tool in your prompts after configuration.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}
```

--------------------------------

### Start OpenCode TUI for a specific directory

Source: https://opencode.ai/docs/zh-cn/tui

Launches the TUI for a specified working directory.

```bash
opencode /path/to/project
```

--------------------------------

### Configure Model Instructions

Source: https://opencode.ai/docs/zh-cn/config

Provide custom instructions to the model by specifying file paths or glob patterns in the 'instructions' array. These files guide the model's behavior.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}
```

--------------------------------

### Remote Configuration Example

Source: https://opencode.ai/docs/zh-cn/config

Illustrates a remote configuration snippet for enabling a Jira MCP server, which might be provided by an organization. This configuration is loaded first and can be overridden by local settings.

```json
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}
```

--------------------------------

### Execute Help Command in TUI

Source: https://opencode.ai/docs/zh-cn/tui

Example of executing a slash command to display the help dialog.

```bash
/help
```

--------------------------------

### Bash Profile Configuration for Self-Hosted GitLab

Source: https://opencode.ai/docs/zh-cn/providers

Example of setting environment variables for self-hosted GitLab in the ~/.bash_profile.

```bash
export GITLAB_INSTANCE_URL=https://gitlab.company.com
export GITLAB_AI_GATEWAY_URL=https://ai-gateway.company.com
export GITLAB_TOKEN=glpat-...
```

--------------------------------

### Install GitHub agent command

Source: https://opencode.ai/docs/zh-cn/cli

Command to install the GitHub agent in a repository, setting up necessary workflows and guiding through configuration.

```bash
opencode github install
```

--------------------------------

### Run OpenCode AI with Docker

Source: https://opencode.ai/docs/zh-cn

Run OpenCode AI directly using Docker. This is a quick way to try OpenCode without local installation.

```bash
docker run -it --rm ghcr.io/anomalyco/opencode
```

--------------------------------

### Setting Environment Variables for Google Vertex AI

Source: https://opencode.ai/docs/zh-cn/providers

Example of setting environment variables for Google Vertex AI when running opencode.

```bash
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json GOOGLE_CLOUD_PROJECT=your-project-id opencode
```

--------------------------------

### Adding Google Vertex AI Environment Variables to ~/.bash_profile

Source: https://opencode.ai/docs/zh-cn/providers

Example of adding environment variables for Google Vertex AI to the bash profile.

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project-id
export VERTEX_LOCATION=global
```

--------------------------------

### Connect to a Running opencode serve Instance

Source: https://opencode.ai/docs/zh-cn/cli

Attach to a running `opencode serve` instance to avoid cold starts of the MCP server on every run.

```bash
# Start a headless server in one terminal
opencode serve

# In another terminal, run commands that attach to it
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
```

--------------------------------

### Custom Configuration Path Example

Source: https://opencode.ai/docs/zh-cn/config

Demonstrates how to use the OPENCODE_CONFIG environment variable to specify a custom path for the OpenCode configuration file. This allows for flexible configuration management outside of standard locations.

```bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"
```

--------------------------------

### Permission Configuration (Global)

Source: https://opencode.ai/docs/zh-cn/agents

Example of configuring global permissions for tools like `edit`, `bash`, and `webfetch` in opencode.json. Permissions can be `ask`, `allow`, or `deny`.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}
```

--------------------------------

### Configure Server Settings

Source: https://opencode.ai/docs/zh-cn/config

Set up server options for `opencode serve` and `opencode web` commands, including port, hostname, mDNS discovery, and CORS origins.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}
```

--------------------------------

### Initialize OpenCode AI in Project

Source: https://opencode.ai/docs/zh-cn

Run the /init command to have OpenCode analyze your project and create an AGENTS.md file. This file helps OpenCode understand project structure and coding standards.

```text
/init
```

--------------------------------

### Navigate to Project Directory

Source: https://opencode.ai/docs/zh-cn

Before initializing OpenCode, navigate to the root directory of your project using the cd command.

```bash
cd /path/to/project
```

--------------------------------

### 使用 opencode.json 引用外部文件

Source: https://opencode.ai/docs/zh-cn/rules

通过 opencode.json 中的 instructions 字段引用多个文档或使用 glob 模式。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}
```

--------------------------------

### Manage App Logs and Agents

Source: https://opencode.ai/docs/zh-cn/sdk

Demonstrates how to write log entries to the service and retrieve a list of available agents.

```javascript
// Write a log entry
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// List available agents
const agents = await client.app.agents()
```

--------------------------------

### Start OpenCode Server

Source: https://opencode.ai/docs/zh-cn/cli

Start an OpenCode server without a TUI for API access. Set OPENCODE_SERVER_PASSWORD for HTTP basic authentication.

```bash
opencode serve
```

--------------------------------

### Custom Configuration Directory Example

Source: https://opencode.ai/docs/zh-cn/config

Illustrates using the OPENCODE_CONFIG_DIR environment variable to point to a custom directory for configuration files. This custom directory is searched for agents, commands, and plugins, similar to the standard .opencode directory.

```bash
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"
```

--------------------------------

### Configure a Local MCP Server

Source: https://opencode.ai/docs/zh-cn/mcp-servers

Add a local MCP server by setting `type` to `"local"`. Specify the launch command and optional environment variables. The `command` can be a string or an array of strings.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}
```

--------------------------------

### Configuring Local MCP Servers

Source: https://opencode.ai/docs/zh-cn/mcp-servers

Add local MCP servers by setting the `type` to `"local"`. Specify the startup command and optional environment variables. An example shows how to add the `@modelcontextprotocol/server-everything` MCP.

```APIDOC
## Local

Add local MCP servers by setting `type` to `"local"` within the MCP object. You can specify the command to run the server and any environment variables.

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}
```

Here's an example for adding the [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP for testing:

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}
```

To use it, add `use the mcp_everything tool` to your prompt:

```txt "mcp_everything"
use the mcp_everything tool to add the number 3 and 4
```
```

--------------------------------

### Get Path Information

Source: https://opencode.ai/docs/zh-cn/sdk

Retrieves information about the current working path.

```javascript
// Get current path information
const pathInfo = await client.path.get()
```

--------------------------------

### opencode.json

Source: https://opencode.ai/docs/zh-cn/agents

Example of configuring agent colors in opencode.json.

```json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}
```

--------------------------------

### Retrieve Configuration

Source: https://opencode.ai/docs/zh-cn/sdk

Fetches system configuration settings and available model providers.

```javascript
const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()
```

--------------------------------

### IDE 命令行工具检查

Source: https://opencode.ai/docs/zh-cn/ide

确认各 IDE 对应的 CLI 命令名称。

```text
VS Code：code
Cursor：cursor
Windsurf：windsurf
VSCodium：codium
```

--------------------------------

### Enabling opencode-helicone-session Plugin in Configuration

Source: https://opencode.ai/docs/zh-cn/providers

Example of enabling the opencode-helicone-session plugin in opencode.json.

```json
{
  "plugin": ["opencode-helicone-session"]
}
```

--------------------------------

### Avante.nvim 配置

Source: https://opencode.ai/docs/zh-cn/acp

在 Avante.nvim 配置中添加 acp_providers，支持可选的环境变量传递。

```lua
{
  acp_providers = {
    ["opencode"] = {
      command = "opencode",
      args = { "acp" }
    }
  }
}
```

```lua
{
  acp_providers = {
    ["opencode"] = {
      command = "opencode",
      args = { "acp" },
      env = {
        OPENCODE_API_KEY = os.getenv("OPENCODE_API_KEY")
      }
    }
  }
}
```

--------------------------------

### opencode.json

Source: https://opencode.ai/docs/zh-cn/agents

Example of configuring the 'top_p' option for response diversity in opencode.json.

```json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}
```

--------------------------------

### New Command

Source: https://opencode.ai/docs/zh-cn/tui

Command to start a new session. Alias: /clear.

```bash
/new
```

--------------------------------

### Manage Sessions and Prompts

Source: https://opencode.ai/docs/zh-cn/sdk

Demonstrates creating sessions, listing them, and sending prompts with or without AI response triggers.

```javascript
// Create and manage sessions
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// Send a prompt message
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})
```

--------------------------------

### Configure Custom Provider in opencode.json

Source: https://opencode.ai/docs/zh-cn/providers

Example opencode.json configuration for a custom OpenAI-compatible provider.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name"
        }
      }
    }
  }
}
```

--------------------------------

### Manual Helicone Provider Configuration

Source: https://opencode.ai/docs/zh-cn/providers

Example of manually configuring the Helicone provider in opencode.jsonc.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o"
        },
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4"
        }
      }
    }
  }
}
```

--------------------------------

### Prompting in TUI

Source: https://opencode.ai/docs/zh-cn/tui

Example of entering a message to prompt the LLM within the TUI.

```text
Give me a quick summary of the codebase.
```

--------------------------------

### opencode.json

Source: https://opencode.ai/docs/zh-cn/agents

Example of passing provider-specific options like 'reasoningEffort' for OpenAI models.

```json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}
```

--------------------------------

### Add Custom Model with ZenMux

Source: https://opencode.ai/docs/zh-cn/providers

Example opencode.json configuration for adding a custom model with ZenMux.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zenmux": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}
```

--------------------------------

### List Available Models

Source: https://opencode.ai/docs/zh-cn/go

Use this endpoint to retrieve a comprehensive list of all available models and their associated metadata.

```bash
https://opencode.ai/zen/go/v1/models
```

--------------------------------

### Control TUI Interface

Source: https://opencode.ai/docs/zh-cn/sdk

Examples for interacting with the terminal user interface, such as appending text to prompts or displaying notifications.

```javascript
// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})
```

--------------------------------

### 撤销修改命令

Source: https://opencode.ai/docs/zh-cn

使用此命令还原 OpenCode 最近一次的修改。

```bash
/undo
```

--------------------------------

### Custom Request Headers for Helicone

Source: https://opencode.ai/docs/zh-cn/providers

Example of adding custom request headers for Helicone in opencode.jsonc.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
        "headers": {
          "Helicone-Cache-Enabled": "true",
          "Helicone-User-Id": "opencode"
        }
      }
    }
  }
}
```

--------------------------------

### 配置 npm 插件

Source: https://opencode.ai/docs/zh-cn/plugins

在 opencode.json 配置文件中指定需要加载的 npm 插件包。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}
```

--------------------------------

### Execute Bash Command in TUI

Source: https://opencode.ai/docs/zh-cn/tui

Example of executing a shell command by prefixing the message with '!'.

```bash
!ls -la
```

--------------------------------

### List Available Models

Source: https://opencode.ai/docs/zh-cn/troubleshooting

Run the 'opencode models' command to view a list of all models that you have access to through your configured providers.

```bash
opencode models
```

--------------------------------

### JSON configuration for agent description

Source: https://opencode.ai/docs/zh-cn/agents

Example of configuring the 'description' option for an agent in opencode.json.

```json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}
```

--------------------------------

### 检查终端真彩色支持

Source: https://opencode.ai/docs/zh-cn/themes

运行此命令以验证终端是否支持 24 位色，输出应为 truecolor 或 24bit。

```bash
echo $COLORTERM
```

--------------------------------

### Markdown configuration for agents

Source: https://opencode.ai/docs/zh-cn/agents

Example Markdown file for defining a subagent named 'review'.

```markdown
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.
```

--------------------------------

### Access Windows Files from WSL

Source: https://opencode.ai/docs/zh-cn/windows-wsl

Demonstrates how to change the directory to a Windows drive (e.g., C:) from within the WSL environment to access your project files.

```bash
cd /mnt/c/Users/YourName/Documents/project
opencode
```

--------------------------------

### opencode.json configuration for agents

Source: https://opencode.ai/docs/zh-cn/agents

Example JSON configuration for defining and customizing agents in opencode.json.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}
```

--------------------------------

### CodeCompanion.nvim 配置

Source: https://opencode.ai/docs/zh-cn/acp

在 Neovim 配置中设置 CodeCompanion 以使用 OpenCode 作为适配器。

```lua
require("codecompanion").setup({
  interactions = {
    chat = {
      adapter = {
        name = "opencode",
        model = "claude-sonnet-4",
      },
    },
  },
})
```

--------------------------------

### .ignore

Source: https://opencode.ai/docs/zh-cn/tools

Example .ignore file to include normally ignored files, such as those in node_modules/, dist/, or build/ directories.

```text
!node_modules/
!dist/
!build/
```

--------------------------------

### MCP 服务器身份验证与管理命令

Source: https://opencode.ai/docs/zh-cn/mcp-servers

用于手动触发身份验证、列出服务器状态及注销凭据的 CLI 命令。

```bash
opencode mcp auth my-oauth-server
```

```bash
opencode mcp list
```

```bash
opencode mcp logout my-oauth-server
```

--------------------------------

### Command Configuration Options

Source: https://opencode.ai/docs/zh-cn/commands

Detailed explanation of the configuration options available for custom commands, including `template`, `description`, `agent`, `subtask`, and `model`.

```APIDOC
## Command Configuration Options

### Template

The `template` option is **required** and defines the prompt sent to the LLM.

```json title="opencode.json"
{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
    }
  }
}
```

### Description

The `description` option provides a brief explanation of the command's functionality, displayed in the TUI.

```json title="opencode.json"
{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}
```

### Agent

The `agent` option is **optional** and specifies which agent executes the command. Defaults to the current agent if not provided.

```json title="opencode.json"
{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}
```

### Subtask

The `subtask` boolean option is **optional** and forces the command to trigger a sub-agent call, even if the agent's mode is set to `primary`.

```json title="opencode.json"
{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}
```

### Model

The `model` option is **optional** and allows overriding the default model for a specific command.

```json title="opencode.json"
{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```
```

--------------------------------

### Create opencode Client in Client-Only Mode

Source: https://opencode.ai/docs/zh-cn/sdk

Create a client instance to connect to an already running opencode instance. This is useful when the server is managed separately.

```javascript
import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})
```

--------------------------------

### File Reference in TUI

Source: https://opencode.ai/docs/zh-cn/tui

Example of referencing a file using '@' in a message for fuzzy file search.

```text
"@packages/functions/src/api/index.ts"
How is auth handled in @packages/functions/src/api/index.ts?
```
Tokens:
Raw