OpenCode Guide
Navigate: Menu

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)

Console (控制台)

引用（references）让 OpenCode 能够通过名称访问当前项目之外的目录。在 opencode.json 或 opencode.jsonc 中添加一个引用，需要时再在客户端中附加其别名。
{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and terminology",
    },
  },
}
附加 docs 之后，让智能体检查相关路径：
Read the attached docs reference and summarize api/authentication.md.
引用适用于文档、共享库、示例，或来自其他仓库的源码。

本地

使用 path 指定本地目录：
{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when working with components or design tokens",
    },
  },
}
路径的解析规则如下：
  • 相对路径以包含配置文件的目录为基准解析。
  • 支持绝对路径。
  • 支持以主目录为基准的路径，例如 ~/docs。
不需要其他字段时，可使用字符串简写：
{
  "references": {
    "docs": "../docs",
    "shared": "~/work/shared",
  },
}
仅当简写字符串以 .、/ 或 ~ 开头时，它才表示本地路径。请使用 ./docs 而非 docs；单独的 docs 值会被解释为 Git 仓库。

Git

使用 repository 指定远程 Git 仓库：
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
    "internal-sdk": {
      "repository": "git@gitlab.example.com:platform/sdk.git",
      "branch": "release/v2",
    },
  },
}
支持的远程形式包括：
  • GitHub owner/repo 简写
  • Git URL
  • 主机/路径形式
  • SCP 风格的远程地址
不支持本地 file: 仓库。
使用字符串简写可跟随远程的默认分支：
{
  "references": {
    "effect": "Effect-TS/effect",
    "sdk": "gitlab.com/platform/sdk",
  },
}
未指定 branch 时，OpenCode 会检出并刷新远程的默认分支。分支名可包含字母、数字、/、_、. 和 -，但不能以 - 开头，也不能包含 ..。
{
  "references": {
    "sdk": {
      "repository": "example/sdk",
      "branch": "release/v2.1",
    },
  },
}

存储

OpenCode 会规范化每个远程地址，并在其全局数据目录下为每个远程和分支各保存一份检出。未显式指定分支时，路径采用如下形式：
opencode/repos/<host>/<repository-path>
在典型的 Linux 安装中，Effect-TS/effect 存储于：
~/.local/share/opencode/repos/github.com/Effect-TS/effect
显式指定分支会附加经编码的 @<branch> 后缀：
~/.local/share/opencode/repos/github.com/Effect-TS/effect@main

刷新

缺失的仓库会异步克隆。当引用加载或重新加载时，以及在对应 Location 中有新的用户提示被接收后，现有检出会在后台被检查。
Prompt admitted → refresh check starts in background → agent continues
当最近一次刷新尝试距今至少 24 小时，或从未记录过任何尝试时，该检出符合刷新条件。刷新会拉取并重置到配置的分支或远程的默认分支。
Last attempt: 25 hours ago → eligible
Last attempt: 2 hours ago  → skipped
刷新行为遵循以下规则：
  • 时间戳在服务重启后仍会保留。
  • 使用同一检出的 Location 共享其时间戳。
  • 失败的尝试会被记录，并仍受 24 小时限制约束。
  • 当某个 Location 未被使用时，不会进行周期性轮询。
  • 克隆或刷新失败不会阻止其他引用加载。
提示不会等待克隆或刷新完成。即使后续的工具读取能看到更新后的检出，附件中仍可能包含较旧的内容；新的引用也可能在其检出就绪之前就已出现。
Attachment created → cached content
Background refresh completes → later tool read sees newer content
缓存的检出是共享的，可能在智能体使用期间被更新。请避免编辑缓存的检出，因为刷新会将其重置。

引导说明

description 用于告知智能体该引用在何时相关。带有 description 的引用会以其别名和解析后的路径出现在智能体指令中。
{
  "references": {
    "docs": {
      "path": "../docs",
      "description": "Use for product behavior and terminology",
    },
  },
}
没有 description 的引用仍可供客户端使用，但不会被自动展示。
{
  "references": {
    "archive": {
      "path": "../archive",
    },
  },
}

可见性

将 hidden 设为 true 可将引用从交互式客户端选择器中移除：
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal service behavior",
      "hidden": true,
    },
  },
}
hidden 仅影响交互式可见性。该引用仍会保留在引用 API 中；若带有 description，也会出现在智能体指令中。

用法

客户端通过根别名附加引用。附件包含根目录下直属文件和子目录的非递归列表。
Attached alias: docs
Ask: Inspect docs/guides/deployment.md and explain the deployment steps.
需要根目录以下的内容时，请让智能体检查具体路径。

权限

引用不会授予额外的工具权限。访问活动 Location 之外的路径仍遵循常规工具规则和 external_directory 权限；编辑还需要相应的编辑权限。
Read ../product-docs/api.md
仅当当前权限允许该外部读取时，请求才会成功。

字段

| 字段 | 本地 | Git | 说明 | | ------------- | -------- | -------- | -------------------------------------------- | | path | 必需 | 否 | 本地目录路径 | | repository | 否 | 必需 | 远程 Git 仓库 | | branch | 否 | 可选 | 要获取并检出的分支 | | description | 可选 | 可选 | 描述智能体应在何时使用它的引导说明 | | hidden | 可选 | 可选 | 在交互式客户端选择器中隐藏该引用 |
完整的 Git 条目可以使用所有 Git 兼容字段：
{
  "references": {
    "sdk": {
      "repository": "example/sdk",
      "branch": "main",
      "description": "Use for SDK implementation details",
      "hidden": false,
    },
  },
}

别名

别名不能为空，也不能包含 /、\、空白字符、反引号或逗号。
Valid:   docs
Invalid: product docs
Invalid: docs/api