### Install GitHub Agent for OpenCode

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/4-scenarios/coder-cicd.md

Run this command in your GitHub repository root to start the installation wizard. It guides you through setting up the GitHub App, generating workflow files, and configuring necessary secrets.

```bash
opencode github install
```

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

### Install and Start OpenCode

Source: https://context7.com/vbgate/learn-opencode/llms.txt

Commands for installing OpenCode on various operating systems and launching the TUI interface with different configurations.

```bash
# macOS / Linux 一键安装
curl -fsSL https://opencode.ai/install | bash

# Windows 使用 Scoop 安装
scoop install opencode

# 验证安装成功
opencode --version
# 输出: opencode x.x.x

# 启动 OpenCode TUI 交互界面
opencode

# 带初始提示语启动
opencode --prompt "帮我分析这个项目的代码结构"

# 使用特定模型启动
opencode -m anthropic/claude-sonnet-4-20250514

# 继续上次会话
opencode -c
```

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

### OpenCode Installation Output

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

This is an example of the expected output when OpenCode is successfully installed on a macOS system.

```bash
Installing OpenCode...

→ Detected: macOS arm64
→ Downloading opencode-darwin-arm64...
  ████████████████████████████████████████ 100%
→ Installing to ~/.opencode/bin/opencode...
→ Updating shell configuration...

✓ Installation complete!

To get started, restart your terminal and run:

  opencode
```

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

### Install OpenCode GitHub Integration

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/14-github.md

Run this command in your GitHub repository's project directory to install the OpenCode GitHub integration. This will guide you through installing the GitHub App, selecting a provider and model, creating a workflow file, and setting up secrets.

```APIDOC
## Install OpenCode GitHub Integration

Run the following command in your GitHub repository's project directory:

```bash
opencode github install
```

This command initiates an interactive setup process that includes:

1. Installing the OpenCode GitHub App.
2. Selecting your preferred AI provider and model.
3. Creating a workflow file (e.g., `.github/workflows/opencode.yml`).
4. Guiding you through setting up necessary secrets (like API keys).
```

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

### Example Batch Tool Call

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/17-tools.md

An example demonstrating how to structure a batch call with 'read', 'grep', and 'bash' tools, including their parameters.

```json
[
  {"tool": "read", "parameters": {"filePath": "src/index.ts", "limit": 350}},
  {"tool": "grep", "parameters": {"pattern": "Session\.updatePart", "include": "src/**/*.ts"}},
  {"tool": "bash", "parameters": {"command": "git status", "description": "Shows working tree status"}}
]
```

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

### Full Experimental Configuration Example (Bash)

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/experimental-features.md

A comprehensive example of experimental feature configuration. Add this to your shell profile and source it. It includes enabling web search, LSP tools, and UI features.

```bash
# ═══════════════════════════════════════════════════════════════
# OpenCode 实验性功能配置
# 添加到 ~/.zshrc 或 ~/.bashrc，然后 source 一下
# ═══════════════════════════════════════════════════════════════

# 一键启用所有实验性功能（下面这些单独开关会自动被包含）
# export OPENCODE_EXPERIMENTAL=true

# ───────────────────────────────────────────────────────────────
# 网络搜索（需要 Exa API，或使用 Zen 托管模型自动启用）
# ───────────────────────────────────────────────────────────────
export OPENCODE_ENABLE_EXA=true           # 启用 websearch 工具

# ───────────────────────────────────────────────────────────────
# LSP（语言服务器协议）增强
# ───────────────────────────────────────────────────────────────
export OPENCODE_EXPERIMENTAL_LSP_TOOL=true  # 启用 LSP 工具
export OPENCODE_EXPERIMENTAL_LSP_TY=true    # 启用实验性 ty Python 服务器

# ───────────────────────────────────────────────────────────────
# 界面与交互

```

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

### Custom Command Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/prompts.md

An example of how to define a custom command for the OpenCode environment.

```markdown
<!-- .opencode/command/review.md ---
description: 代码审查
---

请审查以下代码：
$ARGUMENTS

关注：代码质量、潜在问题、安全隐患、最佳实践
```

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

### Configure and Start OpenCode Server

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/24-cli-automation.md

Set the server password via environment variables to enable authentication before starting the server.

```bash
# 设置服务器密码
export OPENCODE_SERVER_PASSWORD=your-secure-password

# 然后启动
opencode serve
# 现在访问需要认证了
```

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

### Full OpenCode Configuration Example

Source: https://context7.com/vbgate/learn-opencode/llms.txt

A comprehensive example of opencode.json covering basic settings, model configuration, behavior control, TUI settings, provider options, context compaction, keybinds, instructions, and plugins.

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

  // 基础设置
  "username": "developer",
  "theme": "tokyonight",
  "autoupdate": "notify",
  "logLevel": "INFO",
  "snapshot": true,

  // 模型配置
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku",
  "default_agent": "build",

  // 行为控制
  "share": "manual",
  "disabled_providers": [],

  // TUI 界面
  "tui": {
    "scroll_speed": 3,
    "diff_style": "auto"
  },

  // Provider 配置
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000
      }
    }
  },

  // 上下文压缩
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  },

  // 快捷键
  "keybinds": {
    "leader": "ctrl+x",
    "session_new": "<leader>n",
    "agent_cycle": "tab"
  },

  // 额外指令文件
  "instructions": ["docs/rules.md", ".cursor/rules/*.md"],

  // 插件
  "plugin": ["opencode-helicone-session"]
}
```

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

### Install OpenCode SDK

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/10a-sdk-basics.md

Install the OpenCode SDK using npm.

```APIDOC
## Install OpenCode SDK

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

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

### Start OpenCode Web Interface

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/24-cli-automation.md

Launch the server with a web-based interface.

```bash
# 启动带 Web 界面的服务器
opencode web

# 你会看到：
# Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.
# 
#   Local access:      http://localhost:4096
#   Network access:    http://192.168.1.100:4096
```

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

### Install OpenCode via Mise

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02a-install-alternatives.md

使用 Mise 工具进行安装。

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

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

### Example Authentication Credentials List

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/2-daily/05-env-management.md

This is an example output of `opencode auth list`, showing a tree structure of configured credentials and their authentication methods (API or OAuth).

```text
Credentials ~/.local/share/opencode/auth.json
┌
●  Zhipu AI Coding Plan  api
│
●  Google  oauth
│
●  OpenAI  oauth
│
└  3 credentials
```

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

### Agent Permission Configuration Examples

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/02c-agent-permissions.md

Examples of how to configure agent permissions for task execution and skill loading.

```APIDOC
## Agent Permission Configuration Examples

### Configuration Example: Allowing Specific Sub-agents

```jsonc
{
  "agent": {
    "orchestrator": {
      "description": "Task orchestrator Agent, can call specialized sub-agents",
      "mode": "primary",
      "permission": {
        "task": {
          "docs-writer": "allow",      // Allow document writing
          "code-reviewer": "allow",    // Allow code review
          "general": "allow",           // Allow general tasks
          "*": "deny"                 // Deny others
        }
      }
    }
  }
}
```

### Configuration Example: Skill Permissions

```jsonc
{
  "agent": {
    "restricted-agent": {
      "description": "Restricted Agent, can only use specified skills",
      "mode": "subagent",
      "permission": {
        "skill": {
          "*": "deny",                   // Deny all skills
          "docs-writer": "allow",        // Only allow documentation skills
          "translator": "allow"
        }
      }
    }
  }
}
```
```

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

### Example Prompt for HTTP Server Generation

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04e-claude.md

An example prompt to ask Claude to generate a simple HTTP server. This demonstrates initiating a code generation task within OpenCode.

```text
帮我写一个简单的 HTTP 服务器
```

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

### Install OpenCode on macOS/Linux

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

Use this command to download and install OpenCode on macOS and Linux systems. It fetches the installation script and executes it.

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

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

### Advanced Installation Script Parameters

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02a-install-alternatives.md

使用官方安装脚本时可传入特定参数以控制版本或路径配置。

```bash
# 安装指定版本
curl -fsSL https://opencode.ai/install | bash -s -- --version 1.1.6

# 不修改 shell 配置（不自动添加到 PATH）
curl -fsSL https://opencode.ai/install | bash -s -- --no-modify-path

# 从本地二进制安装
./install --binary /path/to/opencode
```

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

### Install OpenCode via Homebrew

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02a-install-alternatives.md

使用官方 Homebrew 公式进行安装，避免使用社区维护版本。

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

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

### Install Ollama on Linux

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04g-ollama.md

Download and execute the official installation script for Ollama on Linux systems.

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

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

### Beast Prompt Template Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/02a-agent-quickstart.md

Example of the default beast.txt prompt structure used for models requiring autonomous research.

```text
You are opencode, an agent - please keep going until the user's query
is completely resolved, before ending your turn and yielding back to the user.

You MUST iterate and keep going until the problem is solved.

THE PROBLEM CAN NOT BE SOLVED WITHOUT EXTENSIVE INTERNET RESEARCH.
You must use the webfetch tool to recursively gather all information...
```

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

### Start OpenCode Web Interface

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/09a-remote-basics.md

Starts the HTTP server and automatically opens the OpenCode web interface in your browser. Options like --port, --hostname, --mdns, and --cors are available.

```bash
opencode web
```

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

```bash
  Local access:      http://localhost:4096
  Network access:    http://192.168.1.100:4096
```

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

### opencode serve - Start Headless Server

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/cli.md

Starts the OpenCode CLI in headless server mode, providing API access for remote interaction.

```APIDOC
## opencode serve

### Description
Starts the headless server mode, providing API access.

### Method
CLI Command

### Endpoint
opencode serve

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options
- **--port** (integer) - The port to listen on.
- **--hostname** (string) - The address to bind to.
- **--mdns** (boolean) - Enable mDNS discovery.
- **--cors** (string) - Allowed CORS origins.

### Request Example
```bash
opencode serve
opencode serve --port 4096 --hostname 0.0.0.0
```

### Response
This command starts a server process. No direct response body is returned to the client initiating the command.
```

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

### Example Model Usage Statistics Output

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/2-daily/05-env-management.md

This is an example of the detailed billing information provided by `opencode stats`. It shows token counts, message counts, and costs per model.

```text
┌────────────────────────────────────────────────────────┐
│                      MODEL USAGE                       │
├────────────────────────────────────────────────────────┤
│ anthropic/claude-opus-4-5-20251101                     │
│  Messages                                       12,548 │
│  Input Tokens                                   241.0M │
│  Cost                                       $1232.5613 │
├────────────────────────────────────────────────────────┤
│ zhipuai-coding-plan/glm-4.7                            │
│  Messages                                        3,023 │
│  Input Tokens                                    68.9M │
│  Cost                                          $0.0000 │
├────────────────────────────────────────────────────────┤
```

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

### Define Skill Description

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/03b-skills-advanced.md

Provide a clear description to guide AI trigger behavior. Use specific examples for better results.

```yaml
description: 帮助处理数据
```

```yaml
description: 从 PDF 中提取表格并转换为 CSV 格式，用于数据分析工作流。当需要填写 PDF 表单或批量处理 PDF 文档时使用。不用于简单 PDF 查看或基本格式转换。
```

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

### Skill Discovery XML Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/03a-skills-basics.md

An XML snippet showing how skills are registered and described when OpenCode starts, making them available to the 'skill' tool.

```xml
<available_skills>
  <skill>
    <name>sql-analysis</name>
    <description>用于分析业务数据：收入、ARR、客户分群...</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>执行代码审查，检查规范、Bug、性能和安全</description>
  </skill>
</available_skills>
```

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

### Launch OpenCode and Initiate Connection

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/1-start/04j-github-copilot.md

Commands to start the OpenCode application and trigger the provider connection flow.

```bash
opencode
```

```text
/connect
```

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

### 初始化本地 Git 仓库

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/2-daily/06-git-basics.md

在项目文件夹中运行 `git init` 来创建一个新的本地 Git 仓库。如果已有仓库，则使用 `git clone` 来克隆远程仓库。

```bash
# 进入你的项目目录
cd /path/to/your/project

# 初始化仓库
git init
```

```bash
git clone https://github.com/<owner>/<repo>.git
cd <repo>
```

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

### Error Handling Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/prompt-guidelines.md

Provides a template for error handling within prompts, guiding the AI on how to respond when information is insufficient, tasks are out of scope, or multiple issues arise.

```markdown
## 错误处理
- 如果信息不足，列出需要补充的信息并说明为什么需要
- 如果问题超出能力范围，说明并建议求助渠道
- 如果有多个独立问题，建议逐个处理
```

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

### Manual Setup: GitHub Workflow Configuration

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/14-github.md

Manually set up OpenCode integration by installing the GitHub App and adding a workflow file to your repository. This workflow file defines when and how OpenCode should be triggered.

```APIDOC
## Manual Setup: GitHub Workflow Configuration

### 1. Install GitHub App

Install the OpenCode agent from the GitHub Marketplace: [github.com/apps/opencode-agent](https://github.com/apps/opencode-agent). Ensure it's installed on the target repository.

### 2. Add Workflow File

Create or update the `.github/workflows/opencode.yml` file in your repository with the following content:

```yaml
name: opencode

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  opencode:
    if: |
      contains(github.event.comment.body, ' /oc') ||
      startsWith(github.event.comment.body, '/oc') ||
      contains(github.event.comment.body, ' /opencode') ||
      startsWith(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: read
      issues: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
```

**Note on `if` condition:** The `if` condition uses `startsWith` and `contains(' /oc')` to ensure the trigger phrase is at the beginning of the line or preceded by a space, preventing accidental matches in URLs or code snippets.
```

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

### 初始化 Git 仓库以开启独立记账

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/2-daily/05-env-management.md

在普通文件夹下运行 `git init`、`git add .` 和 `git commit -m "init"`，可以为该文件夹开启独立记账功能。

```bash
git init
```

```bash
git add .
```

```bash
git commit -m "init"
```

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

### Install OpenCode using Scoop on Windows

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

If you have Scoop installed, use this command to install OpenCode on Windows. Scoop is a command-line installer for Windows.

```powershell
scoop install opencode
```

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

### Install Ollama on Windows

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04g-ollama.md

Download the Ollama installer package from the official website for Windows installation.

```powershell
# From the official website download the installer package
# https://ollama.com/download
```

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

### Install Ollama on macOS

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04g-ollama.md

Use Homebrew to install Ollama on macOS. Ensure you have Homebrew installed first.

```bash
brew install ollama
```

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

### Verify OpenCode Installation

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

Run this command in your terminal after installation to check if OpenCode is installed correctly and display its version.

```bash
opencode --version
```

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

### Verify Ollama Installation

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04g-ollama.md

Check if Ollama is installed correctly by running the version command. This should output the installed version number.

```bash
ollama --version
```

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

### Install Git for Scoop

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

Scoop requires Git to be installed for managing its repositories (buckets). Run this command after installing Scoop.

```powershell
scoop install git
```

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

### Install Scoop Package Manager

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

This command installs the Scoop package manager on Windows by downloading and executing the installation script.

```powershell
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
```

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

### Install Missing Tools (CentOS/RHEL)

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/1-start/02b-install-troubleshoot.md

Installs 'tar' and 'unzip' utilities on CentOS or RHEL systems. These are often required by installation scripts.

```bash
sudo yum install -y tar unzip
```

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

### Specify Additional Instruction Files

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/config-ref.md

Provide a list of extra files containing global instructions for OpenCode. This example includes rules from a 'docs/rules.md' file and a local directory.

```json
"instructions": ["docs/rules.md", ".cursor/rules/*.md"]
```

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

### Install Missing Tools (Ubuntu/Debian)

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/1-start/02b-install-troubleshoot.md

Installs 'tar' and 'unzip' utilities on Ubuntu or Debian systems. These are often required by installation scripts.

```bash
sudo apt install -y tar unzip
```

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

### Example of Successful Plugin Loading Output

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/12a-plugins-basics.md

This output indicates that a plugin has been successfully loaded and a tool registered.

```text
INFO service=plugin path=file:///home/user/my-plugin/dist/index.js loading plugin
INFO service=tool.registry status=started my_custom_tool
INFO service=tool.registry status=completed my_custom_tool
```

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

### Install Dependencies in a New Worktree

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/25-git-worktree.md

Installs project dependencies separately for each worktree. This is necessary because each worktree is an independent working directory and does not share installed modules.

```bash
cd ../project-hotfix
npm install  # or pnpm install
```

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

### Connect a custom provider via CLI

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/providers.md

Interactive command-line steps to register a new provider.

```bash
# 1. 运行 /connect，选择 Other
/connect

# 2. 输入提供商 ID（如 myprovider）

# 3. 输入 API Key
```

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

### Start OpenCode CLI

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04c-zhipu.md

Run the OpenCode command-line interface to begin interacting with AI models.

```bash
opencode
```

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

### Install Scoop with Admin Privileges

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

If running PowerShell as administrator, use this command to install Scoop. It ensures the installation proceeds correctly in an elevated environment.

```powershell
iex "& {$(irm get.scoop.sh)} -RunAsAdmin"
```

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

### Start OpenCode Server Modes

Source: https://context7.com/vbgate/learn-opencode/llms.txt

Launch OpenCode in headless server mode or with a web interface using the 'serve' or 'web' commands. Supports remote access and API calls. Secure with environment variables.

```bash
# 启动无头服务器
opencode serve --port 4096 --hostname 0.0.0.0

# 启动 Web 界面
opencode web --port 4096

# 连接到远程服务器
opencode attach http://10.20.30.40:4096

# 设置服务器认证（强烈建议）
export OPENCODE_SERVER_PASSWORD=your-secure-password
export OPENCODE_SERVER_USERNAME=admin
opencode serve --hostname 0.0.0.0
```

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

### Event Stream Output Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/09b-remote-api.md

Example output format received from the SSE event stream.

```text
event: server.connected
data: {}

event: session.created
data: {"id":"abc123","title":"新会话"}

event: message.created
data: {"sessionID":"abc123","content":"..."}
```

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

### Implement Layer 3 Reference Documentation

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/5-advanced/03b-skills-advanced.md

Provide detailed table structures and SQL examples in a reference file.

```markdown
# Financial Tables Detailed Structure

## monthly_revenue Table

| Field | Type | Description |
|-------|------|-------------|
| account_id | STRING | Account ID |
| month | DATE | Month (first day of each month) |
| mrr | FLOAT | Monthly Recurring Revenue |
| arr | FLOAT | Annual Recurring Revenue |
| segment | STRING | Customer segment |

## Common Queries

### Monthly Revenue by Segment

```sql
SELECT 
  segment,
  DATE_TRUNC(month, MONTH) as period,
  SUM(mrr) as total_mrr
FROM monthly_revenue
WHERE account_id != 'Test'
GROUP BY 1, 2
ORDER BY 2 DESC, 3 DESC
```

### Calculate Month-over-Month Growth

... (more query examples)
```

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

### Connect to IO.NET

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/appendix/providers.md

Command to initiate connection and search for IO.NET, which provides access to over 17 models.

```bash
/connect  # Search IO.NET
```

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

### Complete Jimeng AI Drawing and Download Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/4-scenarios/mcp-web-image-gen.md

This is a full conversational example for automating image generation and download with Jimeng AI. It includes opening the page, inputting prompts, waiting for generation, and downloading the image, with an example file path.

```text
你：打开即梦，画一张"赛博朋克风格的古代城墙"，下载到桌面

AI：
1. 打开 https://jimeng.jianying.com/ai-tool/generate
2. 输入提示词
3. 点击生成
4. 等待完成（约 45 秒）
5. 点击下载
6. 图片已保存到 ~/Downloads/jimeng-xxx.png
```

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

### 设置 Steps 限制

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/02d-agent-advanced.md

通过在配置中设置 steps 限制，可以控制 Agent 的执行步数，便于观察其行为。

```yaml
---
steps: 5  # 只执行 5 步就停止
---
```

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

### Install OpenCode Desktop via Homebrew

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02-install.md

For macOS users with Homebrew, this command installs the OpenCode desktop application.

```bash
brew install --cask opencode-desktop
```

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

### Install OpenCode via Scoop

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/02a-install-alternatives.md

推荐在 Windows 上使用 Scoop 安装，建议使用普通用户权限。

```powershell
scoop bucket add extras
scoop install extras/opencode
```

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

### Event Subscription Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/10b-sdk-reference.md

An example demonstrating how to subscribe to events and handle different event types using TypeScript.

```APIDOC
## Event Subscription Example

### Description
An example demonstrating how to subscribe to events and handle different event types using TypeScript.

### Code Example

```typescript
const events = await client.event.subscribe()

for await (const event of events.stream) {
  switch (event.type) {
    case "message.part.updated":
      // Incremental updates, can be used for streaming display
      if (event.properties.delta) {
        process.stdout.write(event.properties.delta)
      }
      break
      
    case "session.status":
      const { sessionID, status } = event.properties
      if (status.type === "busy") {
        console.log(`Session ${sessionID} is processing...`)
      } else if (status.type === "idle") {
        console.log(`Session ${sessionID} has completed`)
      } else if (status.type === "retry") {
        console.log(`Session ${sessionID} is retrying (${status.attempt})`)
      }
      break
      
    case "permission.updated":
      console.log(`Permission request: ${event.properties.title}`)
      // Can automatically respond to permission requests
      await client.postSessionIdPermissionsPermissionId({
        path: {
          id: event.properties.sessionID,
          permissionID: event.properties.id,
        },
        body: { allow: true },
      })
      break
      
    case "file.edited":
      console.log(`File modified: ${event.properties.file}`)
      break
      
    case "todo.updated":
      console.log(`Todo update:`, event.properties.todos)
      break
  }
}
```
```

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

### Start Headless Server

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/09a-remote-basics.md

Launches the OpenCode HTTP server in headless mode. Use --port to specify the listening port and --hostname to allow network access. Configure CORS origins with --cors.

```bash
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
```

```bash
# Default configuration start (port 4096 or random)
opencode serve
```

```bash
# Specify port and address, allow LAN access
opencode serve --port 4096 --hostname 0.0.0.0
```

```bash
# Allow multiple CORS origins
opencode serve --cors http://localhost:5173 --cors https://app.example.com
```

```bash
# Enable mDNS discovery (automatically sets hostname to 0.0.0.0)
opencode serve --mdns
```

```bash
opencode server listening on http://0.0.0.0:4096
```

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

### Anthropic Prompt Template Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/02a-agent-quickstart.md

Example of the default anthropic.txt prompt structure used when no custom prompt is provided.

```text
You are OpenCode, the best coding agent on the planet.

You are an interactive CLI tool that helps users with software engineering tasks.
Use the instructions below and the tools available to you to assist the user.

# Tone and style
- Only use emojis if the user explicitly requests it
- Your responses should be short and concise
- Output text to communicate with the user

# Task Management
You have access to the TodoWrite tools to help you manage and plan tasks.
Use these tools VERY frequently...
```

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

### Create Server + Client (Recommended)

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/10a-sdk-basics.md

This mode starts both the OpenCode server and client, suitable for standalone scripts and automation scenarios. It allows you to use the client to interact with the server and manage sessions.

```APIDOC
## Create Server + Client (Recommended)

This mode starts both the OpenCode server and client, suitable for standalone scripts and automation scenarios.

### Method

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

const { client, server } = await createOpencode()

// Use client to call APIs
const sessions = await client.session.list()
console.log(`Currently ${sessions.data?.length} sessions exist`)

// Close the server when done
server.close()
```

### ServerOptions Parameters

| Parameter | Type | Description | Default Value |
|---|---|---|---|
| `hostname` | `string` | Server hostname | `127.0.0.1` |
| `port` | `number` | Server port | `4096` |
| `signal` | `AbortSignal` | Abort signal for cancellation | `undefined` |
| `timeout` | `number` | Server startup timeout (ms) | `2000+` |
| `config` | `Config` | Configuration object, overrides `opencode.json` | `{}` |

> **Source**: `packages/sdk/js/src/server.ts:4-10`

### Configuration Override Example

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

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4097,  // Use a different port to avoid conflicts
  timeout: 10000,
  config: {
    model: "anthropic/claude-opus-4-5-thinking",
    logLevel: "DEBUG",
  },
})

console.log(`Server running on ${opencode.server.url}`)

// Close after use
opencode.server.close()
```
```

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

### 默认 .env 文件读取权限配置

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/05-permissions.md

配置 `opencode.json` 中的 `permission`，指定 `.env` 和 `.env.*` 文件读取权限为 `deny`，但允许读取 `.env.example` 文件。

```jsonc
{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"  // 示例文件允许读取
    }
  }
}
```

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

### Get Provider Information

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/10b-sdk-reference.md

Use to get a list of available providers and their default models. The response contains 'providers' and 'default' properties.

```typescript
// 获取提供商信息
const { providers, default: defaults } = (await client.config.providers()).data!
```

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

### 启动无头服务器

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/24-cli-automation.md

使用 `opencode serve` 命令启动一个无头服务器，该服务器仅暴露 API 接口，没有图形界面。适用于需要远程访问或共享会话的场景。

```bash
# 启动无头服务器（只有 API，没有界面）
opencode serve

# 你会看到：
# Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.
```

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

### Configure Server Options

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/24-cli-automation.md

Customize server behavior using command-line flags for networking and discovery.

```bash
# 监听所有网络接口（允许局域网访问）
opencode serve --hostname 0.0.0.0

# 指定端口
opencode serve --port 8080

# 启用 mDNS 发现（局域网内可通过 opencode.local 访问）
opencode serve --hostname 0.0.0.0 --mdns
```

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

### Connect to Baseten

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/appendix/providers.md

Command to initiate connection and search for Baseten services.

```bash
/connect  # Search Baseten
```

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

### Start OpenCode and Initiate Conversation

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/1-start/04e-claude.md

Navigate to your project directory and start the OpenCode interactive interface. You can then select a Claude model and begin your conversation.

```bash
cd /path/to/your/project
opencode
```

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

### Skill Invocation Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/en/5-advanced/03a-skills-basics.md

Example of how Claude determines to load a skill based on user message and invokes it. The result is the SKILL.md content loaded to context.

```javascript
User message: Help me analyze last quarter's revenue data

Claude determines: This is a data analysis task, matches sql-analysis Skill

Claude invokes: skill({ name: "sql-analysis" })

Result: SKILL.md content loaded to context
```

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

### 新建会话

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/2-daily/02-sessions.md

使用 `/new` 命令或快捷键创建新的对话会话，以隔离不同任务的上下文。

```shell
/new
```

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

### Worktree Naming Convention Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/25-git-worktree.md

Example of a naming convention for Git worktrees, using a project name followed by a purpose, suitable for PR reviews.

```bash
my-project-review
```

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

### Agent Prompt Scenario Examples

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/5-advanced/02a-agent-quickstart.md

Demonstration of how custom prompts replace defaults versus how default prompts are injected when the agent prompt is empty.

```markdown
---
description: 代码审查专家
mode: subagent
---

你是代码审查专家，专注于安全和性能...
```

```markdown
---
description: 通用助手
mode: subagent
---
（正文为空）
```

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

### Self-Verification Checklist Example

Source: https://github.com/vbgate/learn-opencode/blob/main/docs/appendix/prompt-guidelines.md

An example of a self-verification checklist for complex tasks, ensuring all requirements are met before outputting the final result. This promotes quality and adherence to guidelines.

```markdown
## 自检清单
完成前确认：
- [ ] 每个主角都有清晰的弧线
- [ ] 起承转合节奏合理
- [ ] 核心冲突能贯穿全文
- [ ] 亮点足以吸引目标读者
```