鱼梦江湖 @Yumengjh

简体中文

English

简体中文

English

外观

OpenCode 笔记

复制页面

约 2130 字大约 7 分钟

2026-01-16

官方文档 | 中文文档

npm install opencode-ai -g

接口AI（接口中转）

/compact 用于压缩之前对话的上下文，把之前的对话提炼为一个简洁的摘要，释放模型的上下文窗口

除了内置的 / 命令，还可以自定义命令，在配置文件夹中创建一个command 文件夹，在其中以 md 文件的形式定义自己的命令，元字段查看官方

在配置文件夹中，创建一个 agent 文件夹，用于自定义智能体，在其中创建相关的 md 文件

mode 字段可以是 subagent ，表示它由主智能体来自动调度，在后台运行

还可以是 primary ，也就是主智能体，可以直接 tap 按键显式的切换智能体

全局配置：~/.config/opencode/opencode.json

创建项目级别 opencode.json 配置文件

进入项目目录（最好是项目根目录），创建/编辑 opencode.json

opencode 会从当前目录往上找 opencode.json，直到最近的 Git 目录为止；找到就用，能覆盖全局配置。

所以最稳的放置位置是：项目根目录（git root）。

AGENTS.md 是 opencode 的“项目级指令文件”。

  • 它不是聊天记忆
  • 也不是 AI 自动学习产生的东西
  • 而是：你明确写给 agent 的规则和背景说明

只要 agent 在这个项目中运行：

  • 每一次执行都会读取 AGENTS.md
  • 把它当成“必须遵守的前提条件”

所以它表现得像记忆，但本质是固定说明书

没有 AGENTS.md 时，agent 往往会：不知道项目结构，随意选技术方案，改你不想动的代码，忽略测试 / 规范 / 约束

配置文件：opencode 在启动时会先在当前目录找配置文件，找不到就一路向上遍历目录，最多遍历到最近的 Git 目录（通常就是 repo root）为止

所以它的行为更像：“以 Git 仓库为边界，找最近的项目配置”，而不是无限向上找。

OpenCode 支持 JSON 和 JSONC（带注释） 格式。

合并机制：是 merge，不是 replace，配置会合并在一起：不冲突的键都会保留，冲突的键按优先级覆盖。

优先级顺序

标准顺序是：

  1. Remote（组织默认）（最低）
  2. Global：~/.config/opencode/opencode.json（覆盖 remote）
  3. Custom path：OPENCODE_CONFIG=/path/to/xxx.json（夹在 global 和 project 之间）
  4. Project：项目根目录的 opencode.json（最高，覆盖 global/remote）

SKILL

为每个技能名称创建一个文件夹，并在其中放置一个 SKILL.md。OpenCode 会搜索以下位置：

项目配置：.opencode/skill/<name>/SKILL.md

每个 SKILL.md 必须以 YAML frontmatter 开头。只识别以下字段：

  • name（必需）
  • description（必需）
  • license（可选）
  • compatibility（可选）
  • metadata（可选，字符串到字符串的映射）

未知的 frontmatter 字段会被忽略。

在 timeline 中选中任意的对话记录后：

Revert undo messages and file 
Copy message text to clipboard
Fork create a new session

Revert undo messages and file 相当于 回滚/撤销，会把会话状态回到“这条记录之前/对应的那个时刻”，不止回滚聊天消息，还会把 当时 agent 对文件做的修改也一起撤回（所以叫 messages and file）

适合场景：agent 改飞了、改多了，想回到某个“干净”的节点重新来

注意点：回滚后，后面的那段历史通常就等于被你“作废/覆盖”了

Copy message text to clipboard 就是 复制这条消息文本 到剪贴板，只复制“消息内容”（通常不包含文件 diff、附件、工具输出的完整结构）

适合：把某条 prompt / 输出贴到 PR、文档、群里，抽取一段命令/总结复用

Fork create a new session 相当于 从这里分叉一个新会话，新 session 会继承你在这条记录时的上下文/状态，但之后的对话会走新的分支，不影响原来的 session

适合：想尝试另一种方案，但不想破坏当前会话，同一个问题做 A/B 路线：比如“重构方案 A”和“方案 B”，这通常是最安全的“试错方式”：原 session 保底，新 session 放开试。

为重复任务创建自定义命令，自定义命令让你指定在 TUI 中执行该命令时要运行的提示，内置的命令如 /init、/undo、/redo、/share、/help等

创建 .opencode/command/test.md：

<!-- .opencode/command/test.md -->
---
description: 运行带覆盖率的测试
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

运行完整的测试套件并生成覆盖率报告，显示任何失败。
专注于失败的测试并建议修复。

frontmatter 定义命令属性，内容成为模板，通过输入 / 后跟命令名称来使用命令。

可以通过 OpenCode 配置或在 command/ 目录中创建 markdown 文件来添加自定义命令。

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // 这成为命令的名称
    "test": {
      // 这是将发送给 LLM 的提示
      "template": "运行完整的测试套件并生成覆盖率报告，显示任何失败。\n专注于失败的测试并建议修复。",
      // 这在 TUI 中显示为描述
      "description": "运行带覆盖率的测试",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

使用 $ARGUMENTS 占位符向命令传递参数。

<!-- .opencode/command/component.md -->
---
description: 创建新组件
---

创建一个名为 $ARGUMENTS 的新 React 组件，支持 TypeScript。
包含适当的类型和基本结构。
/component Button

$ARGUMENTS 将被替换为 Button。

也可以使用位置参数访问单个参数：

  • $1 - 第一个参数
  • $2 - 第二个参数
  • $3 - 第三个参数
  • 以此类推…

当 markdown 提示文件的内容需要执行命令后才知道，可以使用 ! command 将 bash 命令 输出注入到提示中。

例如，创建一个分析测试覆盖率的自定义命令：

复制

<!-- .opencode/command/analyze-coverage.md -->
---
description: 分析测试覆盖率
---

以下是当前的测试结果：
!`npm test`

根据这些结果，建议改进以提高覆盖率。

或者审查最近的更改：

<!-- .opencode/command/review-changes.md -->
---
description: 审查最近的更改
---

最近的 git 提交：
!`git log --oneline -10`

审查这些更改并建议任何改进。

命令在项目的根目录运行，其输出成为提示的一部分。

使用 @ 后跟文件名在命令中包含文件。

<!-- .opencode/command/review-component.md -->
---
description: 审查组件
---

审查 @src/components/Button.tsx 中的组件。
检查性能问题并建议改进。

文件内容会自动包含在提示中。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "claude-opus-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.jiekou.ai/anthropic",
        "apiKey": ""
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.jiekou.ai/openai/v1",
        "apiKey": ""
      }
    },
    "gemini": {
      "options": {
        "baseURL": "https://api.jiekou.ai/openai/v1",
        "apiKey": "",
      },
      "models": {
        "antigravity-claude-opus-4-5-thinking": {
          "name": "Claude Opus 4.5 Thinking (Antigravity)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  },
  // "plugin": ["oh-my-opencode", "opencode-antigravity-auth@beta"]
}

oh-my-opencode.json

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "librarian": {
      "model": "opencode/glm-4.7-free"
    },
    "explore": {
      "model": "opencode/grok-code"
    },
    "oracle": {
      "model": "openai/gpt-5.2"
    },
    "frontend-ui-ux-engineer": {
      "model": "gemini/gemini-3-pro-preview"
    },
    "document-writer": {
      "model": "gemini/gemini-3-flash"
    },
    "multimodal-looker": {
      "model": "gemini/gemini-3-flash"
    }
  }
}

可以输入@ 然后选择智能体开始干活

在提示词内加上 ulw ，它会在干活的时候尽可能的调用它一切的潜能，把任务分配给几个智能体，并且并行运行

输入 /ralph-loop ，这个模式可以强制 AI 长时间的循环，对一个非常难的任务进行持续的工作

MCP 加得越多 ≠ 一定越聪明；过多 MCP 很容易烧钱 + 吃上下文 + 降稳定性。

在 opencode CLI 里，每一个 MCP server，本质都会做几件事之一（或多件）：

  • 注入 system / tool 级别的说明
  • 暴露 工具 schema（JSON）
  • 在调用时返回 结构化 or 非结构化内容
  • 有些 MCP 还会在 启动或对话初期主动提供背景信息

这些东西都会进入：

  • prompt tokens
  • tool call tokens
  • tool response tokens

全都算钱，也全都占上下文窗口。

open code MCP 服务器

AI API 中转商/提供商，在 OpenCode 的配置

只要它是 OpenAI 协议兼容（最常见），就按 openai-compatible 的方式配。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myrelay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Relay",
      "options": {
        "baseURL": "https://YOUR-RELAY-DOMAIN/v1",
        "apiKey": "YOUR_KEY_HERE"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o via relay" },
        "gpt-4o-mini": { "name": "GPT-4o-mini via relay" }
      }
    }
  }
}