🚀 OpenCode 完全指南

从入门到精通的系统化教程

OpenCode 不仅是一个 AI 编程助手，更是一个完整的 AI Agent 开发平台。本教程涵盖 Agents（代理）、Tools（工具）、Skills（技能）、SDK、权限系统、配置管理等所有功能，帮助你从零开始掌握 OpenCode 的核心能力。

核心功能模块

10+

内置工具

50+

实际案例

1000+

行代码示例

🤖

Agents 代理系统

了解 OpenCode 的代理架构，包括 Primary Agent 和 Subagent，掌握如何配置和切换不同类型的 AI 助手。

核心功能

🛠️

Tools 工具系统

掌握所有内置工具（bash、edit、write、read、grep 等），学习如何配置工具权限和自定义工具。

基础功能

📦

Skills 技能系统

深入理解 Skills 的概念和用法，学习如何创建、使用和分享可复用的技能模块。

高级功能

💻

SDK 编程接口

通过 SDK 实现程序化控制，创建自动化工作流，集成 OpenCode 到你的项目中。

开发者

🔐

权限管理系统

学习 OpenCode 的权限模型，配置安全策略，保护你的系统和数据安全。

安全功能

⚙️

配置系统

掌握 OpenCode 的配置方法，包括模型选择、主题设置、代理配置等。

配置

📑 教程目录

🤖 第一章：Agents 代理系统 🛠️ 第二章：Tools 工具系统 📦 第三章：Skills 技能系统 💻 第四章：SDK 编程接口 🔐 第五章：权限管理 ⚙️ 第六章：配置系统 🎨 第七章：实战案例 ❓ 第八章：常见问题

📑 教程目录

📖 详细章节

基于你的 codebase 中 50+ 个实际会话和 13+ 个项目案例编写的完整教程。

第一章

🤖 Agents 代理系统

Primary Agent vs Subagent，Build/Plan/General/Explore 代理详解，代理配置与切换

⏱️ 约 30 分钟

第二章

🛠️ Tools 工具系统

所有内置工具详解，工具权限配置，自定义工具与 MCP 服务器

⏱️ 约 45 分钟

第三章

📦 Skills 技能系统

Skills 概念与用法，创建自定义 Skills，Skills 复用与分享

⏱️ 约 25 分钟

第四章

💻 SDK 编程接口

SDK 安装与配置，会话管理，文件操作，事件订阅，并发控制

⏱️ 约 60 分钟

第五章

🔐 权限管理系统

权限模型详解，安全规则配置，危险操作防护，权限最佳实践

⏱️ 约 20 分钟

第六章

⚙️ 配置系统

配置文件结构，模型配置，主题设置，环境变量，高级配置

⏱️ 约 25 分钟

第七章

🎨 实战案例

50+ 个来自你的 codebase 的真实案例，包括自动化、爬虫、开发、部署等

⏱️ 持续更新

第八章

❓ 常见问题

常见问题解答，错误排查指南，性能优化技巧，学习路径建议

⏱️ 参考资源

💻 代码示例：从你的项目中提炼

以下示例基于你的 codebase 中实际运行的 OpenCode 会话和项目：

// 示例 1: 使用 SDK 创建并行任务扫描项目
// 来源: /Users/sun/codebase/projects/task-platform/workers/opencode-worker-runner.js

const { createOpencodeClient } = require('@opencode-ai/sdk');

async function scanProjects() {
    const client = createOpencodeClient({ 
        baseUrl: 'http://localhost:4096' 
    });
    
    // 并行创建多个扫描任务
    const tasks = [
        '扫描 codebase/projects 目录',
        '列出所有 JavaScript 文件',
        '分析 OpenCode SDK 使用情况'
    ];
    
    const results = await Promise.all(
        tasks.map(task => client.session.create({ title: task }))
    );
    
    return results;
}
            

// 示例 2: 配置自定义 Agent
// 来源: /Users/sun/codebase/ai-config-research/opencode-agents-docs.md

"agent": {
    "build": {
        "mode": "primary",
        "model": "anthropic/claude-sonnet-4-20250514",
        "tools": {
            "write": true,
            "edit": true,
            "bash": true
        }
    },
    "plan": {
        "mode": "primary",
        "model": "anthropic/claude-haiku-4-20250514",
        "tools": {
            "write": false,
            "edit": false,
            "bash": false
        }
    }
}
            

// 示例 3: 配置权限系统
// 来源: /Users/sun/codebase/ai-config-research/opencode-config.md

"permission": {
    "read": {
        "*": "allow",
        "*.env": "deny"
    },
    "write": "allow",
    "bash": {
        "*": "allow",
        "rm *": "deny",
        "rm -rf *": "deny",
        "sudo *": "ask"
    }
}
            