OpenCode 实践指南

发表于 更新于 分类于 ， 阅读次数： Waline： 本文字数： 3.1k 阅读时长 ≈ 3 分钟
命令行 AI 编程助手 OpenCode 的安装配置、多代理协作与技能系统详解

1. OpenCode 简介

OpenCode 是命令行 AI 编程助手，采用模块化代理架构，支持多代理并行协作。核心特点：

  • 命令行原生：纯终端操作，无 GUI 依赖
  • 代理系统：支持 Explore、Librarian、Build 等专业化代理
  • 技能扩展：通过 SKILL.md 定义可复用工作流
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4F46E5', 'primaryTextColor': '#000', 'primaryBorderColor': '#3730A3', 'lineColor': '#6366F1', 'secondaryColor': '#10B981', 'tertiaryColor': '#F59E0B'}}}%%
flowchart LR
    A["用户"] --> B["OpenCode"]
    B --> C["代理系统"]
    B --> D["技能系统"]
    B --> E["会话管理"]

    C --> C1["Explore"]
    C --> C2["Librarian"]
    C --> C3["Build"]

    classDef primary fill:#4F46E5,stroke:#3730A3,color:#fff
    classDef success fill:#10B981,stroke:#059669,color:#fff
    classDef info fill:#06B6D4,stroke:#0891B2,color:#fff

    class A,B primary
    class C,D,E success
    class C1,C2,C3 info

2. 安装与配置

2.1 一键安装

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

2.2 配置文件

1
2
3
~/.config/opencode/opencode.json          # 主配置：API 密钥、默认模型
~/.config/opencode/oh-my-opencode.json   # 插件配置：代理定义、技能映射
~/.local/share/opencode/auth.json         # 认证信息：Provider API 密钥

配置 Provider：使用 /connect 命令添加 API 密钥，密钥存储于 auth.json。

3. 核心操作

3.1 项目初始化

1
/init

执行后自动创建或更新 AGENTS.md，内容包括：

配置项说明
项目概述技术栈、架构模式
构建命令编译、测试、部署流程
编码规范代码风格、命名约定
目录结构模块划分、文件组织

3.2 常用命令

1
2
3
opencode stats          # 查看会话统计
opencode agent list     # 列出可用代理
opencode session info   # 当前会话状态

3.3 任务管理

操作快捷键/命令
挂起任务Ctrl + Z
恢复任务fg
切换子任务Ctrl+X + 方向键
返回主任务Ctrl+X + ↑
后台执行/background

4. 技能系统

技能将复杂任务标准化为可复用工作流，通过 SKILL.md 定义。

4.1 技能文件位置

1
2
3
4
5
6
7
8
9
# 项目级（推荐）
.opencode/skill/<name>/SKILL.md

# 全局级
~/.config/opencode/skill/<name>/SKILL.md

# 兼容 Claude Code
.claude/skills/<name>/SKILL.md
~/.claude/skills/<name>/SKILL.md

5. Oh My OpenCode

Oh My OpenCode 是 OpenCode 增强插件，提供多代理协作、技能系统、自定义命令等高级功能。

核心能力：

功能说明
多代理系统并行启动专业化子代理
技能系统SKILL.md 定义工作流
会话管理跨会话持久化记忆
自定义命令集成外部工具和脚本

5.1 多代理协作

%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#4F46E5', 'actorTextColor': '#000', 'actorBorder': '#3730A3', 'signalColor': '#6366F1', 'activationBkgColor': '#E0E7FF', 'activationBorderColor': '#4F46E5'}}}%%
sequenceDiagram
    autonumber
    participant U as "用户"
    participant OC as "主代理"
    participant A1 as "Explore"
    participant A2 as "Librarian"
    participant A3 as "Build"

    U->>OC: "发起复杂任务"
    activate OC
    OC-->>U: "创建任务清单"

    par 并行执行
        OC->>A1: "代码库探索"
        activate A1
        A1-->>OC: "结构分析结果"
        deactivate A1
    and
        OC->>A2: "文档检索"
        activate A2
        A2-->>OC: "参考资料"
        deactivate A2
    and
        OC->>A3: "代码生成"
        activate A3
        A3-->>OC: "实现代码"
        deactivate A3
    end

    OC->>OC: "聚合分析"
    OC-->>U: "返回完整方案"
    deactivate OC

    Note over U,OC: "用户交互"
    Note over OC,A3: "代理协作"

5.2 协作优势

  • 并行处理：子代理同时执行，缩短总耗时
  • 专业分工：代理专注各自领域，提升质量
  • 动态调整：主代理根据中间结果调整策略
  • 结果聚合：统一综合多源信息

6. 参考资料