OpenCode 安装、使用方法详细全解

洛星核

142人浏览 · 2026-06-12 09:07:39

洛星核 · 2026-06-12 09:07:39 发布

OpenCode 安装、使用方法详细全解

信息来源：OpenCode 官方文档 (opencode.ai/docs)、官网 (opencode.ai)、GitHub、社区资源
项目地址：https://opencode.ai
GitHub：https://github.com/opencode-ai/opencode

一、项目概述

1.1 简介

OpenCode 是一款开源 AI 编程 Agent，支持在终端（TUI）、桌面应用（Beta）、浏览器（Web）和 IDE 中运行。它兼容 Claude Code 工作流，提供完整的代码生成、修改、调试和代码审查能力。

1.2 核心亮点

开源：MIT 许可证，完全开源
160,000+ GitHub Stars，900+ 贡献者，7.5M 月活开发者
75+ LLM 提供商支持：Anthropic、OpenAI、Google、xAI、Ollama 等
内置免费模型：无需注册账户即可使用
隐私优先：不存储用户代码或上下文数据
多平台支持：macOS、Windows（WSL）、Linux
多模式运行：TUI、CLI、Web、IDE、Desktop、Server

1.3 语言与架构

OpenCode 由 Go 语言编写，基于 Go CLI 应用架构。采用客户端-服务器模型：

TUI 是连接到本地 HTTP 服务器的客户端
服务器暴露 OpenAPI 3.1 规范端点
支持多客户端同时连接
可从 Go 语言源码编译或预编译二进制安装

二、安装方法

2.1 一键安装脚本（推荐）

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

2.2 Node.js 生态

# NPM
npm install -g opencode-ai

# BUN
bun install -g opencode-ai

# PNPM
pnpm add -g opencode-ai

# YARN
yarn global add opencode-ai

2.3 Homebrew（macOS / Linux）

brew install anomalyco/tap/opencode

官方推荐使用 OpenCode tap（anomalyco/tap），比 Homebrew 官方 formula 更新更频繁。

2.4 Arch Linux

# 官方仓库（稳定版）
sudo pacman -S opencode

# AUR（最新版）
paru -S opencode-bin

2.5 Windows

推荐：使用 WSL2 运行
Chocolatey：通过 WSL 中的包管理器安装
原生 Windows 支持仍在完善中

2.6 桌面应用（Beta）

支持 macOS、Windows、Linux，可在 opencode.ai 官网下载页面获取。

2.7 系统要求

现代终端模拟器（推荐 WezTerm、Alacritty、Ghostty、Kitty）
终端需支持 truecolor（24-bit 颜色）
需要 LLM 提供商的 API Key（或使用内置免费模型）

三、快速开始

3.1 首次运行

# 启动 TUI（终端界面）
opencode

# 指定项目目录
opencode /path/to/project

3.2 连接模型提供商

首次使用需要添加 API Key：

方式一：TUI 内交互配置

在 TUI 中输入 /connect 命令，选择提供商并输入 API Key。认证信息存储在 ~/.local/share/opencode/auth.json。

方式二：环境变量

在 .env 或 shell 配置中设置对应提供商的环境变量：

# Anthropic
export ANTHROPIC_API_KEY="your-key"

# OpenAI
export OPENAI_API_KEY="your-key"

# 其他提供商类似...

3.3 选择模型

# 在 TUI 中查看所有可用模型
/models

# 在 CLI 中指定模型
opencode --model anthropic/claude-sonnet-4-5 "Your prompt"

3.4 开始对话

在 TUI 输入框中直接输入问题即可，例如：

Give me a quick summary of the codebase.
Add retry logic to API calls and update tests
Review the authentication module for security issues

四、使用方式（详细）

OpenCode 提供 6 种主要使用模式：

4.1 TUI（终端用户界面）

启动方式：

opencode
opencode /path/to/project

核心功能：

文件引用（@语法）

使用 @ 进行模糊文件搜索引用
文件内容自动添加到对话中
配置了 references 的目录也可通过 @alias 引用
使用 @alias/ 可自动补全引用目录中的文件

Bash 命令（!前缀）

以 ! 开头的消息将执行 Shell 命令
命令输出作为工具结果加入对话
示例：!ls -la、!npm test

消息输入：

直接输入文本后按 Enter 发送
Shift+Enter 或 Ctrl+Enter 插入换行
/editor 使用外部 $EDITOR 编写长消息

会话管理：

/new — 新建会话
/sessions — 列出并切换历史会话
/compact — 压缩长对话上下文
/export — 导出对话为 Markdown
/share — 生成公开分享链接
/undo — 撤销最后一条消息（基于 Git）
/redo — 重做已撤销的消息
/quit 或 Ctrl+C — 退出

Agent 切换：

Tab — 在 Build（构建）和 Plan（规划）Agent 之间切换
Build：启用所有工具，用于完整开发工作
Plan：受限模式，文件编辑和 Bash 设为 ask，用于分析和规划

子 Agent 调用：

@general — 通用子 Agent，用于并行任务
@explore — 只读快速探索，用于文件查找和代码搜索
@scout — 只读外部研究，用于克隆依赖仓库、检查源码

4.2 CLI（命令行模式）

基础用法：

# 启动 TUI（默认）
opencode

# 一次性执行（非交互式）
opencode run "Explain how closures work in JavaScript"

# 指定模型
opencode run --model anthropic/claude-sonnet-4-5 "Refactor auth module"

# 继续上次会话
opencode --continue
opencode -c

# 指定会话
opencode --session ses_abc123
opencode -s ses_abc123

# Fork 会话（不修改原会话）
opencode --continue --fork

# 指定 Agent
opencode --agent plan "Analyze this codebase"

# 指定项目目录
opencode /path/to/project

TUI 子命令标志：

标志	简写	说明
`--continue`	`-c`	继续上次会话
`--session`	`-s`	指定会话 ID
`--fork`	-	Fork 会话时继续
`--prompt`	-	使用指定 prompt
`--model`	`-m`	指定模型（provider/model）
`--agent`	-	指定 Agent
`--port`	-	监听端口
`--hostname`	-	监听主机名
`--mdns`	-	启用 mDNS 发现
`--mdns-domain`	-	自定义 mDNS 域名
`--cors`	-	额外允许的 CORS 源

Agent 管理命令：

# 管理 Agent
opencode agent [command]

# 创建新 Agent（交互式向导）
opencode agent create

MCP 管理命令：

# 列出所有 MCP 服务器
opencode mcp list

# 手动认证 MCP 服务器
opencode mcp auth <server-name>

# 调试 MCP 连接
opencode mcp debug <server-name>

# 查看 OAuth 状态
opencode mcp auth list

# 移除凭证
opencode mcp logout <server-name>

4.3 Web 界面

启动方式：

opencode web

配置选项：

选项	命令	说明
端口	`--port 4096`	默认自动选择可用端口
主机名	`--hostname 0.0.0.0`	默认 localhost，设为 0.0.0.0 可局域网访问
mDNS	`--mdns`	自动广播为 opencode.local
mDNS 域名	`--mdns-domain <name>`	自定义 mDNS 域名

安全提示：

设置 OPENCODE_SERVER_PASSWORD 环境变量以启用 HTTP Basic Auth
本地使用无需密码，但网络访问必须设置
Windows 用户建议在 WSL 中运行

4.4 IDE 集成

支持 IDE： VS Code、Cursor、Windsurf、VSCodium 等（任何支持终端的 IDE）

使用方式：

操作	Mac	Windows/Linux
快速启动	`Cmd+Esc`	`Ctrl+Esc`
新会话	`Cmd+Shift+Esc`	`Ctrl+Shift+Esc`
文件引用	`Cmd+Option+K`	`Alt+Ctrl+K`

安装：

打开 IDE 集成终端
运行 opencode（扩展自动安装）
或手动在扩展市场搜索 “OpenCode”

特性：

上下文感知：自动共享当前选中代码或标签页
文件引用快捷键：插入 @File#L37-42 格式引用

4.5 GitHub 集成

功能：

在 Issue/PR 评论中使用 /opencode 或 /oc 命令
OpenCode 在 GitHub Actions runner 中执行任务
支持 Issue 分诊、Bug 修复、功能实现

安装：

opencode github install

安装步骤：

安装 GitHub App（github.com/apps/opencode-agent）
创建 GitHub Actions 工作流（.github/workflows/opencode.yml）
设置仓库 Secrets（API Key 等）

工作流示例：

name: opencode
on:
  issue_comment:
    types: [created]
jobs:
  opencode:
    if: contains(github.event.comment.body, '/opencode') || contains(github.event.comment.body, '/oc')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false
      # ... OpenCode 步骤

4.6 GitLab 集成

安装：

opencode gitlab install

两种方式：

GitLab CI 方式：使用社区 CI 组件 nagyv/gitlab-opencode
GitLab Duo 方式：在 Issue/MR 评论中 @opencode

4.7 Server 模式

启动方式：

opencode serve

配置选项：

标志	默认值	说明
`--port`	`4096`	监听端口
`--hostname`	`127.0.0.1`	监听主机名
`--mdns`	`false`	启用 mDNS 发现
`--mdns-domain`	`opencode.local`	自定义 mDNS 域名
`--cors`	`[]`	额外允许的浏览器源

认证：

OPENCODE_SERVER_PASSWORD=your-password opencode serve
OPENCODE_SERVER_USERNAME=custom-user opencode serve

使用场景：

远程连接：跨机器连接 OpenCode 实例
编程集成：通过 HTTP API 调用 OpenCode
SDK 生成：基于 OpenAPI 3.1 规范自动生成 SDK

4.8 分享功能

使用方法：

在 TUI 中输入 /share 命令
生成公开链接并复制到剪贴板
对话默认不共享，需手动触发

注意： 共享对话对拥有链接的人公开可见。

五、配置系统

5.1 配置文件格式

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

Schema： $schema: "https://opencode.ai/config.json"

5.2 配置文件位置与优先级

配置文件合并而非替换，后加载的配置仅对冲突键覆盖：

优先级（低→高）	位置	说明
1	`.well-known/opencode`	组织级默认配置（Remote）
2	`~/.config/opencode/opencode.json`	全局配置（用户偏好）
3	`$OPENCODE_CONFIG`	自定义配置路径（环境变量）
4	项目根目录 `opencode.json`	项目级配置
5	`.opencode/` 目录	Agent、命令、插件等
6	`$OPENCODE_CONFIG_CONTENT`	运行时内联覆盖
7	`/Library/Application Support/opencode/`	托管配置文件（macOS）

5.3 核心配置选项

完整配置示例：

{
  "$schema": "https://opencode.ai/config.json",

  // 模型
  "model": "anthropic/claude-sonnet-4-5",

  // 自动更新
  "autoupdate": true,

  // 服务器配置
  "server": {
    "port": 4096
  },

  // 权限控制
  "permission": {
    "bash": "allow",
    "edit": "ask",
    "webfetch": "allow"
  },

  // 格式化器
  "formatter": true,

  // 自定义指令
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ],

  // 引用目录
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "产品文档"
    },
    "effect": {
      "repository": "effect-ts/effect",
      "branch": "main",
      "description": "Effect TS 源码"
    }
  }
}

5.4 TUI 配置

配置文件：tui.json 或 tui.jsonc

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "leader_timeout": 2000,
  "scroll_speed": 3,
  "diff_style": "auto",
  "mouse": true
}

六、Provider 配置（75+ 支持）

6.1 内置免费模型

OpenCode 提供内置免费模型，无需注册即可直接使用。

6.2 主要提供商

提供商	认证方式	环境变量
OpenCode Zen（官方）	API Key	opencode.ai/auth
OpenCode Go（$10/月）	API Key	opencode.ai/auth
Anthropic	API Key / OAuth	-
OpenAI	ChatGPT OAuth / API Key	-
Google Vertex AI	服务账号 JSON	`GOOGLE_APPLICATION_CREDENTIALS`
Amazon Bedrock	AWS 凭证	`AWS_ACCESS_KEY_ID` 等
Azure OpenAI	API Key	`AZURE_RESOURCE_NAME`
GitHub Copilot	OAuth（Device Code）	-
GitLab Duo	OAuth / PAT	`GITLAB_TOKEN`
xAI (Grok)	API Key / OAuth	`XAI_API_KEY`
DeepSeek	API Key	-
Groq	API Key	-
OpenRouter	API Key	-
NVIDIA	API Key	`NVIDIA_API_KEY`
Together AI	API Key	-
Fireworks AI	API Key	-
Hugging Face	Token	-
Perplexity	API Key	-
Moonshot AI (Kimi)	API Key	-
MiniMax	API Key	-
Ollama（本地）	自定义	baseURL: `http://localhost:11434/v1`
LM Studio（本地）	自定义	baseURL: `http://127.0.0.1:1234/v1`
llama.cpp（本地）	自定义	baseURL: `http://127.0.0.1:8080/v1`

6.3 自定义 Provider 模板

{
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "显示名称",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:MY_API_KEY}"
      },
      "models": {
        "my-model": {
          "name": "模型显示名",
          "limit": { "context": 200000, "output": 65536 }
        }
      }
    }
  }
}

6.4 OpenCode Zen

官方模型服务，经过编码 Agent 任务测试和基准验证：

提供优化的高质量模型
地址：opencode.ai/zen
解决跨提供商性能和一致性不一致问题

6.5 OpenCode Go

低价订阅服务，$10/月，提供 12 个编码模型：

地址：opencode.ai/go
适合不想管理多个 API Key 的用户
支持开源模型，无需担心成本

七、内置工具

工具	功能	权限键
bash	执行 Shell 命令	`bash`
edit	精确字符串替换修改文件	`edit`
write	创建新文件或覆盖现有文件	`edit`
read	读取文件内容（支持行范围）	`read`
grep	正则表达式搜索文件内容（ripgrep）	`grep`
glob	模式匹配查找文件	`glob`
apply_patch	应用 patch 文件	`edit`
lsp	LSP 代码智能（实验性）	`lsp`
skill	加载 SKILL.md 技能文件	`skill`
todowrite	管理任务列表	`todowrite`
webfetch	抓取网页内容	`webfetch`
websearch	Exa AI 网络搜索	`websearch`
question	向用户提问（多选项）	`question`

所有工具默认启用，可通过 permission 字段控制（allow/ask/deny）。

八、Agent 系统

8.1 主要 Agent（Primary）

Agent	模式	说明
Build	primary	默认 Agent，启用所有工具，用于开发
Plan	primary	受限 Agent，用于分析和规划，不修改代码

切换：Tab 键

8.2 子 Agent（Subagent）

Agent	模式	说明
General	subagent	通用 Agent，完整工具，用于并行任务
Explore	subagent	只读探索，文件查找和代码搜索
Scout	subagent	只读外部研究，克隆仓库和检查源码

调用：在消息中 @提及，如 @general 帮我搜索

8.3 隐藏系统 Agent

compaction — 自动压缩长上下文
title — 自动生成会话标题
summary — 自动生成会话摘要

8.4 Agent 配置

JSON 配置：

{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "permission": { "edit": "allow", "bash": "allow" },
      "temperature": 0.3,
      "color": "#ff6b6b",
      "steps": 10
    }
  }
}

Markdown 配置（放在 ~/.config/opencode/agents/ 或 .opencode/agents/）：

---
description: 代码审查
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
---

你是代码审查专家...

配置字段：

字段	说明
`description`	Agent 描述（必填）
`mode`	`primary` / `subagent` / `all`
`model`	模型（`provider/model-id`）
`prompt`	自定义系统提示
`temperature`	随机性（0.0-1.0）
`steps`	最大迭代次数
`permission`	权限控制
`color`	UI 颜色
`top_p`	多样性控制
`hidden`	隐藏不出现在 @ 补全中
`disable`	禁用该 Agent

九、权限系统

9.1 权限级别

级别	说明
`allow`	自动执行
`ask`	每次执行前提示确认（可一次/本次会话/拒绝）
`deny`	阻止执行

9.2 全局配置

{
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

9.3 细粒度规则

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/**/*.mdx": "allow"
    }
  }
}

9.4 所有权限键

read、edit、glob、grep、bash、task、skill、lsp、question、webfetch、websearch、external_directory、doom_loop

十、Rules 与 AGENTS.md

10.1 AGENTS.md

类似于 Cursor 的规则文件，向 LLM 提供项目特定指令：

初始化： 在 TUI 中运行 /init 自动生成

应包含：

构建、lint、测试命令
命令顺序和验证步骤
架构和仓库结构说明
项目特定惯例和注意事项

10.2 规则文件优先级

项目级：项目根目录 AGENTS.md
全局级：~/.config/opencode/AGENTS.md
Claude Code 兼容：CLAUDE.md 和 ~/.claude/CLAUDE.md

10.3 自定义指令

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

支持 glob 模式和远程 URL（5 秒超时）。

十一、斜杠命令（完整列表）

命令	快捷键	别名	功能
`/connect`	-	-	添加提供商 API Key
`/compact`	`Ctrl+X C`	`/summarize`	压缩当前会话
`/details`	-	-	切换工具执行详情
`/editor`	`Ctrl+X E`	-	外部编辑器编写消息
`/exit`	`Ctrl+X Q`	`/quit`, `/q`	退出 OpenCode
`/export`	`Ctrl+X X`	-	导出对话为 Markdown
`/help`	-	-	显示帮助
`/init`	-	-	创建/更新 AGENTS.md
`/models`	`Ctrl+X M`	-	列出可用模型
`/new`	`Ctrl+X N`	`/clear`	新会话
`/redo`	`Ctrl+X R`	-	重做（Git 管理）
`/sessions`	`Ctrl+X L`	`/resume`, `/continue`	列出和切换会话
`/share`	-	-	分享会话
`/themes`	`Ctrl+X T`	-	列出主题
`/thinking`	-	-	切换推理块可见性
`/undo`	`Ctrl+X U`	-	撤销（Git 管理）
`/unshare`	-	-	取消分享

自定义命令

JSON 配置：

{
  "command": {
    "test": {
      "template": "运行完整测试套件并显示覆盖率报告...",
      "description": "运行带覆盖率的测试",
      "agent": "build",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

Markdown 文件（.opencode/commands/ 或 ~/.config/opencode/commands/）：

---
description: 运行带覆盖率的测试
agent: build
---

运行完整测试套件并显示覆盖率报告...

模板变量： $ARGUMENTS、$1/$2、!`command`、@filename、subtask: true

十二、MCP Server 集成

12.1 本地 MCP

{
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "environment": { "MY_ENV_VAR": "value" },
      "timeout": 5000
    }
  }
}

12.2 远程 MCP

{
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": { "Authorization": "Bearer MY_API_KEY" },
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

12.3 常用 MCP 示例

Sentry：https://mcp.sentry.dev/mcp（OAuth 认证）
Context7：https://mcp.context7.com/mcp（文档搜索）
Grep by Vercel：https://mcp.grep.app（GitHub 代码搜索）

12.4 MCP 管理命令

opencode mcp list              # 列出所有 MCP 服务器
opencode mcp auth <name>       # 手动认证
opencode mcp debug <name>      # 调试连接
opencode mcp auth list         # 查看 OAuth 状态
opencode mcp logout <name>     # 移除凭证

十三、自定义工具

存放位置：

项目级：.opencode/tools/
全局级：~/.config/opencode/tools/

示例（TypeScript）：

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "使用 Python 相加两个数字",
  args: {
    a: tool.schema.number().describe("第一个数"),
    b: tool.schema.number().describe("第二个数"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".opencode/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  }
})

文件名即工具名，多导出格式：<文件名>_<导出名>。

上下文对象： agent、sessionID、messageID、directory、worktree

十四、代码格式化器

内置支持 15+ 格式化器：

格式化器	文件扩展名
prettier	.js/.ts/.html/.css/.md/.json/.yaml
ruff	.py/.pyi
biome	.js/.ts/.html/.css/.md/.json/.yaml
gofmt	.go
rustfmt/cargofmt	.rs
clang-format	.c/.cpp/.h/.hpp
ktlint	.kt/.kts
shfmt	.sh/.bash
terraform	.tf/.tfvars
rubocop	.rb/.rake
dart	.dart
cljfmt	.clj/.cljs
mix	.ex/.exs/.eex
zig	.zig/.zon
air	.R

启用所有：

{ "formatter": true }

自定义：

{
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "extensions": [".js", ".ts", ".jsx", ".tsx"],
      "environment": { "NODE_ENV": "development" }
    }
  }
}

十五、主题（Themes）

15.1 内置主题

tokyonight、everforest、ayu、catppuccin、catppuccin-macchiato、gruvbox、kanagawa、nord、matrix、one-dark、system

15.2 切换方式

TUI 中运行 /themes
tui.json 配置："theme": "tokyonight"

15.3 自定义主题

创建 ~/.config/opencode/themes/my-theme.json 或项目级 .opencode/themes/my-theme.json，支持 40+ 个颜色字段。

十六、键盘快捷键

16.1 Leader Key

默认 Ctrl+X，超时 2000ms（可配置），所有功能键通过 Leader Key 组合。

16.2 主要快捷键

快捷键	功能
`Ctrl+X C`	压缩会话
`Ctrl+X E`	打开外部编辑器
`Ctrl+X Q`	退出
`Ctrl+X X`	导出对话
`Ctrl+X M`	切换模型
`Ctrl+X N`	新会话
`Ctrl+X L`	会话列表
`Ctrl+X U`	撤销
`Ctrl+X R`	重做
`Ctrl+X T`	切换主题/推理等级
`Ctrl+X G`	会话时间线
`Ctrl+P`	命令面板
`Ctrl+R`	重命名会话
`Ctrl+D`	删除会话
`Tab`	切换 Agent
`Esc`	中断会话
`Shift+Enter`	输入换行
`Right/Left`	切换子会话
`Up/Down`	父/子会话导航

十七、References（引用）

17.1 本地目录引用

{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "产品文档和行为规范"
    },
    "sdk": "../sdk"
  }
}

17.2 Git 仓库引用

{
  "references": {
    "effect": {
      "repository": "effect-ts/effect",
      "branch": "main",
      "description": "Effect TS 源码"
    }
  }
}

OpenCode 会自动克隆到本地缓存目录并检出对应分支。

十八、模型配置

18.1 设置默认模型

{
  "model": "provider_id/model_id"
}

完整 ID 格式：provider_id/model_id（如 opencode/gpt-5.1-codex）

18.2 模型选项配置

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-5-20250929": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        }
      }
    },
    "openai": {
      "models": {
        "gpt-5": {
          "options": {
            "reasoningEffort": "high",
            "textVerbosity": "low"
          }
        }
      }
    }
  }
}

18.3 模型变体（Variants）

{
  "provider": {
    "opencode": {
      "models": {
        "gpt-5": {
          "variants": {
            "high": { "reasoningEffort": "high" },
            "low": { "reasoningEffort": "low" }
          }
        }
      }
    }
  }
}

内置变体：

Anthropic：high（默认）、max
OpenAI：none、minimal、low、medium、high、xhigh
Google：low、high

18.4 模型加载优先级

--model 命令行 > 配置文件 > 上次使用的模型 > 内部优先级

十九、Agent Skills

OpenCode 支持 SKILL.md 技能文件（与 Claude Code 兼容），可通过 skill 工具加载到对话中。技能文件可以是 .md 格式，包含 YAML frontmatter 和 markdown 内容。

二十、其他高级特性

20.1 LSP 集成（实验性）

启用方式：OPENCODE_EXPERIMENTAL_LSP_TOOL=true

提供定义跳转、引用查找、悬停信息等代码智能功能。

20.2 ACP Support

支持 ACP（Agent Communication Protocol）标准。

20.3 Auto Compaction

OpenCode 会自动压缩长对话上下文，防止上下文窗口溢出。

20.4 Session 管理

基于 Git 的会话管理（需 Git 仓库）
支持 undo/redo 消息级撤销
会话 fork 功能
会话自动标题生成

20.5 通配符支持

权限配置支持通配符：

* — 匹配零或多个任意字符
? — 匹配单个字符
~/ 或 $HOME — 家目录扩展

二十一、配置文件完整路径汇总

配置类型	全局路径	项目路径
主配置	`~/.config/opencode/opencode.json`	`<project>/opencode.json`
TUI 配置	`~/.config/opencode/tui.json`	`<project>/tui.json`
认证信息	`~/.local/share/opencode/auth.json`	-
Agent	`~/.config/opencode/agents/*.md`	`.opencode/agents/*.md`
命令	`~/.config/opencode/commands/*.md`	`.opencode/commands/*.md`
主题	`~/.config/opencode/themes/*.json`	`.opencode/themes/*.json`
工具	`~/.config/opencode/tools/*.ts`	`.opencode/tools/*.ts`
AGENTS.md	`~/.config/opencode/AGENTS.md`	`<project>/AGENTS.md`

二十二、总结与建议

22.1 OpenCode 的优势

开源免费：MIT 协议，内置免费模型
极致灵活：75+ Provider，支持几乎所有主流 LLM
多模式运行：TUI、CLI、Web、IDE、Desktop、Server 6 种模式
隐私优先：代码和上下文不存储
强大的配置系统：多层配置合并、细粒度权限、自定义一切
Agent 系统：Build/Plan 双 Agent + 子 Agent 并行
生态集成：GitHub、GitLab、MCP、LSP
Go 语言实现：高性能、跨平台、单二进制部署
Claude Code 兼容：AGENTS.md、SKILL.md 兼容

22.2 适用场景

终端开发者：原生 TUI 体验，键盘驱动操作
团队项目：多配置层级、共享 Agent 和命令
CI/CD 集成：GitHub/GitLab Actions 自动执行
隐私敏感环境：本地模型（Ollama/LM Studio）、不存储数据
多模型需求：无缝切换 75+ 提供商
远程开发：Server 模式 + Web 界面 + mDNS 发现

22.3 注意事项

旧仓库 opencode-ai/opencode（Node.js 版本）已归档，新仓库使用 Go 重写
Windows 原生支持仍在完善中，推荐使用 WSL2
LSP 工具、部分实验性功能需要环境变量启用
桌面应用目前仍为 Beta 阶段
MCP OAuth 流程会自动处理，但首次可能需要手动认证

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

AI UI 生成革命：当 GPT-5.6 把前端开发效率提升 5 倍，开发者该恐惧还是拥抱？ - 微元算力(weytoken)

AI编程社区

手机远程控制Mac上的Claude Code开发：完整实战指南

组件作用为什么选它Tailscale内网穿透无需公网IP，点对点直连，延迟低SSH + tmux远程终端 + 会话保持断网不丢进度，多窗口并行AI编程助手原生终端体验，直接改代码随时随地：只要有网络就能连接Mac开发稳定可靠：tmux保护会话，网络波动不影响安全可控：Tailscale的ACL + SSH密钥双重保护原生体验：Termius提供真正的终端，不是远程桌面适用场景通勤路上处理紧急Bug

AI编程社区

AI领域最新资讯日报 | 2026年6月12日

Claude Mythos 5重磅发布 🚀Anthropic推出新一代模型Mythos 5，声称可1天处理5000万行代码。同时发布Fable 5，具备反蒸馏机制，检测到蒸馏行为会自动降智。Claude Corps国家奖学金计划同步启动，助力早期职业人士。中国AI图像生成登顶全球HiDream-O1-Image-1.5登顶文生图榜单，中国第一、全球第二，超越谷歌和英伟达。国产模型在国际竞赛中取得