Opencode入门

ghgxm520

93人浏览 · 2026-04-16 16:35:16

ghgxm520 · 2026-04-16 16:35:16 发布

这里写自定义目录标题

Opencode

Opencode

安装

安装比较简单相见：点击这里

初始化

在项目目录下打开终端，输入“opencode”启动opencode
在这里插入图片描述
输入：/init 命令
OpenCode 会分析你的项目并在项目根目录创建一个 AGENTS.md 文件。
这有助于 OpenCode 理解项目结构和编码规范。

配置

类型	常见路径	说明
全局配置	~/.opencode.json	适用于所有项目的通用设置（如 API Key）。
项目配置	./opencode.json	位于项目根目录，仅对当前项目生效。
Agent 规则	./AGENTS.md	初始化后的文件，用于定义特定 Agent 的行为准则和技能。

1. 基础配置：接入模型服务
首先，你需要定义模型提供者（Provider）。通常在全局配置文件 ~/.opencode.json 中进行。

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "baseUrl": "https://api.anthropic.com"
    },
    "openai": {
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1"
    }
  },
  "agents": {
    "coder": {
      "model": "claude-3-5-sonnet-20240620",
      "provider": "anthropic"
    }
  }
}

配置说明：

providers: 字典结构，键名（如 anthropic）供后续引用。

baseUrl: 如果你使用代理或兼容接口（如 OneAPI），请在此修改地址。

agents.coder: 定义主编程助手的身份，model 必须是该 Provider 支持的具体模型 ID。

2. 安全与权限配置：保护你的系统
OpenCode 具有执行 Shell 命令的能力。为了防止 AI 误删文件，你需要在项目根目录的 opencode.json 中设置权限。

{
  "permissions": {
    "allow": {
      "read": ["src/", "tests/", "package.json"],
      "write": ["src/", "tests/"],
      "commands": ["npm test", "git status"]
    },
    "deny": {
      "commands": ["rm -rf /", "mkfs", "curl -X POST"],
      "read": [".env", "node_modules/"]
    },
    "autoApprove": ["read"]
  }
}

配置说明：

allow.read/write: 限制 AI 只能操作特定的工作目录。

allow.commands: 白名单机制。只有在这里列出的命令才会被执行。

deny: 黑名单机制。即使 AI 尝试执行危险命令也会被内核拦截。

autoApprove: 自动批准列表。设置为 [“read”] 意味着 AI 读取文件时不会弹窗问你，但写入和运行命令仍需你手动确认。

3.进阶：自定义 Agent 行为 (AGENTS.md)
除了 JSON 配置，OpenCode 支持通过 Markdown 文件定义 Agent 的“灵魂”。

配置实例 (项目根目录下的 AGENTS.md)：

# Coder Agent Rules
- 所有的代码变量名必须使用驼峰命名法 (camelCase)。
- 每一段逻辑修改后，必须自动运行 `npm test` 验证。
- 严禁在代码中留下任何调试用的 console.log。
- 如果修改涉及到 API，必须同步更新 `docs/api.md`。

配置说明：

这是对 JSON 配置的有力补充。OpenCode 在初始化时会读取此文件作为 System Prompt 的一部分。

适用于团队规范约束。

通过 Ollama 配置 OpenCode 使用本地模型。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

在这个示例中：

ollama 是自定义的提供商 ID，可以是任意字符串。
npm 指定该提供商使用的包。这里使用 @ai-sdk/openai-compatible 来兼容任何 OpenAI 兼容的 API。
name 是该提供商在 UI 中显示的名称。
options.baseURL 是本地服务器的端点地址。
models 是模型 ID 到其配置的映射。模型名称会显示在模型选择列表中。

skills配置：

Skills 的核心就是：一个文件夹 + 一个 SKILL.md 文件。（文件名固定为 SKILL.md）
配置路劲：参考claude code，使用opencode时将claude路径换成opencode就行

项目级：.opencode/skills/ 目录（OpenCode 原生 Skill）
这是 OpenCode 原生的 Skill 机制，与 .claude/skills/ 结构几乎一致。Agent 会在 skill 工具描述中看到所有可用 Skill 的名称和描述，并按需加载。

除了在项目目录下创建skills的文件夹外，还可以在根目录的“AGENTS.md” 或者自定义的“opencode.json”
配置文件中定义skill技能。

项目根目录/
└── .opencode/
    └── skills/
        └── naming-convention/      # 文件夹名 = skill 名
            └── SKILL.md            # 必须全大写

skill示例：

first-skill/
└── SKILL.md   （唯一必需，SKILL必须大写，md必须小写）

完整格式的具体内容：

---                                 #  YAML frontmatter 开始（顶格）
name: code-comment-expert           # 必填：技能名（也是 /slash 命令名）
description: >-                     # 必填：最关键一行！Claude 靠它判断是否加载
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
  常见触发场景：加注释、注释一下、加文档、explain this、improve readability

trigger_keywords:                   # 强烈推荐（大幅提升自动触发率）
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
  - comment this
  - readability

version: 1.0                        # 可选
author: yourname                    # 可选
---                                 # ← YAML 结束

# 这里开始是正文（Markdown）—— Claude 真正执行时的指令

你现在是「专业代码注释专家」。

## 核心原则
- 只在缺少注释或可读性明显不足处添加
- 优先使用英文 JSDoc / TSDoc 风格
- 复杂逻辑 / 非明显意图处额外加一行中文解释
- 注释精炼，每行不超过 80 字符
- 绝不修改原有逻辑

## 输出格式（严格遵守）
1. 先输出完整修改后的代码块（用 ```语言 包裹）
2. 再用 diff 形式展示只改动注释的部分
3. 最后说明加了哪些注释、理由

现在直接开始处理用户提供的代码，不要闲聊。

可选的Skill 的目录结构：
在这里插入图片描述
最简单的skill结构：

my-skill/
  └── code-comment-expert/          # 技能文件夹名
      └── SKILL.md                  # 唯一必填文件（必须全大写 + .md 小写）

项目中创建skill：
在这里插入图片描述

插件

on-my-opencode

https://github.com/code-yeongyu/oh-my-openagent

oh-my-opencode则被视为OpenCode的灵魂核心，它引入了革命性的多代理协作机制。该插件内置了多个“专家级”AI代理，各自负责不同领域的任务。例如，Sisyphus负责协调与综合执行，Librarian专注于查阅文档和代码实现，Oracle则处理复杂问题与Debug，还有专门的前端工程师。

这种分工协作模式，使得AI能更专业、更深入地参与到编程的各个环节。值得一提的是，该插件不仅与OpenCode深度整合，还兼容Claude
Code的技术栈，实现了生态优势的吸收与扩展。

安装：

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

OhMyOpenCode 四大核心 Agent 详解
基于你升级后的版本，四大核心 Agent 全部可以通过 Tab 循环切换（固定顺序：Sisyphus → Hephaestus → Prometheus → Atlas），各有明确的职责定位和工作哲学。

1. Sisyphus → 团队协作，负责执行
2. Hephaestus → 自主深度完成，负责执行
3. Prometheus → 负责规划（只动口，不动手）
4. Atlas → 负责按照计划执行（指挥家）
安装后默认使用：
在这里插入图片描述

superpowers

https://github.com/obra/superpowers

安装：

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

opencode-antigravity-auth

通过安装谷歌开发的opencode-antigravity-auth插件，用户可以直接在OpenCode中接入并使用谷歌的AI模型。这相当于为开发者打开了一扇通往强大计算能力的大门，且无需额外付费。安装过程十分简便，仅需在对话框中输入指定命令，随后在新的命令行窗口中完成谷歌OAuth授权，即可开始使用。

https://github.com/NoeFabris/opencode-antigravity-auth