OpenCode 手册

程小虎2026-03-19 11:35:00

📘 OpenCode 手册

参考官网：https://opencode.ai/docs/zh-cn/open in new window

1. OpenCode 是什么

OpenCode 是一个开源 AI 编码代理，主要面向终端内的开发工作流，支持 TUI、CLI、Web 界面以及 IDE 扩展等使用方式。它的核心目标是让开发者可以直接在项目上下文里与 AI 协作，完成代码理解、修改、执行命令、规则约束和工具调用等工作。

从官方文档来看，OpenCode 的几个关键特征包括：

以终端工作流为核心，适合日常工程开发。
支持多种模型提供商与本地模型接入。
支持规则文件、代理、工具权限、MCP 等扩展能力。
既能交互式使用，也能通过命令行进行自动化调用。

2. 安装与前置条件

2.1 前置条件

在开始使用前，通常需要具备以下条件：

一个现代终端环境。
可用的大模型 API Key，或已配置好的本地模型服务。
一个实际项目目录，用于让 OpenCode 理解和操作代码上下文。

官方文档中推荐的终端环境包括常见现代终端模拟器；如果在 Windows 环境中使用，也可以结合本地终端或 WSL 工作流。

2.2 安装方式

官方提供的常见安装方式包括脚本安装、包管理器安装以及平台包安装。

常见安装命令：

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

此外，文档也提到可通过 npm、bun、pnpm、yarn、Homebrew、Chocolatey、Scoop、Docker 等方式安装，适合不同平台和团队环境。

3. 快速开始

3.1 启动 OpenCode

进入项目目录后，可直接启动：

opencode

或者指定一个项目路径：

opencode /path/to/project

3.2 连接模型提供商

首次使用时，通常需要通过 /connect 完成模型提供商配置。官方文档中将这一步作为入门的关键流程之一。

常见流程：

/connect

然后在界面中选择提供商，并按提示填写 API Key 或完成认证。

3.3 初始化项目规则

进入项目后，官方推荐执行 /init 来生成项目规则文件。这个过程通常会创建 AGENTS.md，用于定义当前仓库中的约束、习惯和工作方式。

/init

AGENTS.md 的作用通常包括：

说明项目结构。
记录编码规范。
约束 AI 在仓库中的行为方式。
明确测试、构建、提交等流程要求。

如果项目团队长期使用 OpenCode，建议把该文件提交到版本库中。

4. 常见使用方式

4.1 TUI 模式

TUI 是 OpenCode 的核心使用方式之一。启动后，用户可以在终端界面中直接提问、引用文件、执行命令和切换代理。

常见能力包括：

通过自然语言提问代码相关问题。
使用 @ 引用文件或路径。
使用 ! 执行 Bash 命令。
通过斜杠命令管理会话、配置和功能。

示例：

How is auth handled in @packages/functions/src/api/index.ts

4.2 CLI 模式

除了交互界面外，OpenCode 也支持命令行模式，适合脚本化或自动化场景。

示例：

opencode run "Explain closures"
opencode serve
opencode web

常见含义：

opencode run：执行一次非交互任务。
opencode serve：启动无界面服务。
opencode web：启动 Web 界面。

4.3 Web 与 IDE 扩展

官方文档中也覆盖了 Web 界面和 IDE 集成能力。对于不希望始终停留在终端中的用户，这两类入口可以提供更图形化的操作方式，但整体能力模型仍然围绕 OpenCode 的代理、工具和上下文机制展开。

5. 常用命令与交互方式

官方文档中提到的常用交互包括以下几类。

5.1 斜杠命令

常见命令：

/connect：连接模型提供商。
/init：初始化项目规则。
/models：查看可用模型。
/undo：撤销最近一步。
/redo：恢复撤销内容。
/share：生成分享链接。

5.2 文件与命令引用

@文件路径：引用文件或模糊匹配文件。
!命令：执行 Bash 命令。

这两种方式让 OpenCode 可以在同一个交互界面中同时完成“理解代码”和“执行环境操作”两类任务。

5.3 会话相关命令

opencode session list
opencode export [sessionID]
opencode import session.json
opencode stats --days 7

这些命令可用于查看历史会话、导出会话、导入会话，以及统计使用情况。

6. 配置体系

6.1 配置文件位置与优先级

根据官方文档，OpenCode 支持多层级配置，且不同来源之间存在覆盖顺序。常见配置来源包括：

远程配置。
全局配置，例如 ~/.config/opencode/opencode.json。
通过环境变量指定的自定义配置。
项目内配置，例如 opencode.json。
.opencode 目录下的局部配置。

这意味着：团队可维护项目级配置，个人也可保留全局偏好，两者可以组合使用。

6.2 配置示例

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "theme": "",
  "tui": {
    "scroll_speed": 3,
    "diff_style": "auto"
  }
}

从这个示例可以看出，配置文件通常覆盖以下内容：

默认大模型与小模型。
自动更新行为。
终端界面展示设置。
主题或交互偏好。

6.3 常见环境变量

官方文档中提到了一些常见环境变量，例如：

export OPENCODE_CONFIG=/path/to/custom-config.json
export OPENCODE_DISABLE_AUTOUPDATE=1
export OPENCODE_EXPERIMENTAL=1
export OPENCODE_SERVER_PASSWORD=your-password

这些变量适用于以下场景：

指定自定义配置文件。
禁用自动升级。
打开实验特性。
为服务模式配置访问密码。

7. 模型与 Provider 配置

7.1 新手推荐路径

官方文档中对新用户较友好的方式是通过 OpenCode Zen 接入，即通过 /connect 选择官方推荐方案，再按照页面引导完成认证或配置。

7.2 常见第三方 Provider

OpenCode 支持多类模型提供商，例如：

Anthropic
OpenAI
DeepSeek
其他兼容接口

典型流程是：

/connect
/models

前者用于配置提供商，后者用于查看当前可用模型。

7.3 本地模型

官方文档也提供了本地模型的接入方式，例如 Ollama 这类本地推理服务。示例配置：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      }
    }
  }
}

这种方式适合对数据本地化、成本控制或离线能力有要求的场景。

8. 核心能力

8.1 Agents

官方文档将代理能力作为 OpenCode 的重要组成部分。常见代理包括：

Build：默认主代理，具备较完整工具能力。
Plan：偏只读分析，适合规划、审查和理解任务。
General：常用于一般性研究。
Explore：适合代码搜索与上下文探索。

常见交互方式包括：

使用 Tab 在主代理之间切换。
通过 @agent-name 显式调用某个子代理。

8.2 Tools 与权限控制

OpenCode 支持多种工具，并允许通过权限配置控制工具的使用方式。

示例：

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

权限值常见含义：

allow：允许直接执行。
ask：执行前先征求确认。
deny：禁止执行。

这种配置适合用于平衡效率与安全，尤其是在生产仓库或高风险操作中。

8.3 Rules

规则系统通常由 AGENTS.md 驱动，既支持项目级规则，也支持全局级规则。它的价值在于：

给 AI 明确边界。
减少重复指令输入。
让不同项目拥有各自的行为规范。

8.4 MCP 集成

OpenCode 支持 MCP（Model Context Protocol）服务器接入，用于扩展外部工具和系统能力。

示例配置：

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

这类集成适合把日志、监控、外部服务和内部平台能力接入 OpenCode 工作流。

9. 高级功能

9.1 Skills

官方文档中包含了 Skills 能力，用于给代理按需注入特定领域知识或流程。

常见放置路径：

.opencode/skills/<name>/SKILL.md

根据文档说明，SKILL.md 通常需要包含：

name
description

这让技能可以被系统识别并在需要时加载。

9.2 自定义命令

OpenCode 支持通过配置定义自定义命令，从而把常用流程模板化。

示例：

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage",
      "description": "Run tests with coverage"
    }
  }
}

适合把测试、发布、检查、生成文档等动作封装成统一入口。

9.3 会话分享

官方文档提到 /share 可用于生成分享链接。分享行为一般支持如下模式：

manual
auto
disabled

团队协作时，这类能力可用于复盘会话、共享方案或远程协同。

10. 故障排除

10.1 日志位置

官方文档给出了常见日志目录：

macOS/Linux：~/.local/share/opencode/log/
Windows：%USERPROFILE%\.local\share\opencode\log

遇到启动异常、Provider 初始化失败或行为异常时，应先查看日志。

10.2 常见问题

根据官方资料，常见排查方向包括：

无法启动时，查看日志并尝试升级。
出现 ProviderInitError 时，清理本地状态后重新认证。
出现 API 调用异常时，清理缓存目录后重试。
Linux 下复制粘贴有问题时，补齐剪贴板依赖工具。

11. 常见命令速查

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

# 启动
opencode
opencode /path/to/project

# Web 界面
opencode web --port 4096

# 服务模式
opencode serve

# 配置 Provider
/connect

# 查看模型
/models

# 初始化项目规则
/init

# 查看认证 Provider
opencode auth list

# 会话管理
opencode session list
opencode export [sessionID]
opencode import session.json

# 用量统计
opencode stats --days 7

# 代理与 MCP
opencode agent create
opencode agent list
opencode mcp add
opencode mcp auth <server-name>

12. 术语说明

以下术语建议保留官方原写法：

OpenCode
TUI
CLI
AGENTS.md
SKILL.md
MCP
LSP
ACP
OAuth
API
JSON / JSONC
npm
WSL
Zen
Build / Plan / General / Explore

13. 使用建议

结合官网内容，实际使用 OpenCode 时可以优先遵循以下顺序：

先配置 Provider 或本地模型。
在真实项目目录中启动 OpenCode。
通过 /init 建立 AGENTS.md 规则文件。
明确工具权限配置，避免高风险操作失控。
逐步接入 MCP、Skills、自定义命令等高级能力。

对于团队使用场景，建议统一：

项目级规则文件。
常用模型与权限配置。
命令模板和技能目录结构。

这样能显著降低协作中的上下文成本。

14. 官方参考地址

官网文档：https://opencode.ai/docs/zh-cn/open in new window
GitHub：https://github.com/anomalyco/opencodeopen in new window
Discord：https://opencode.ai/discordopen in new window

本手册依据 OpenCode 官方中文文档整理，适合作为入门与日常查阅版本。如需查看最完整、最新的配置项、命令参数和平台说明，请以官网原文为准。