opencode 使用指南

OpenCode 全面使用指南

OpenCode 是一个开源的 AI 编程代理(AI Coding Agent),提供终端 TUI、桌面应用和 IDE 扩展三种形态,支持 75+ 家 LLM 提供商和本地模型。以下指南基于官方文档(opencode.ai/docs)整理。


一、安装

推荐方式(一行脚本):

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

其他方式:

方式 命令
npm npm install -g opencode-ai
bun bun install -g opencode-ai
Homebrew brew install anomalyco/tap/opencode
Arch sudo pacman -S opencode 或 paru -S opencode-bin
Windows (Scoop) scoop install opencode
Windows (Chocolatey) choco install opencode
Docker docker run -it --rm ghcr.io/anomalyco/opencode

注意: Windows 强烈建议使用 WSL;使用脚本安装时,要使用现代终端模拟器(WezTerm、Alacritty、Ghostty、Kitty 等)。

升级 / 卸载:

1
2
3
opencode upgrade            # 升级到最新版
opencode upgrade v0.1.48 # 升级到指定版本
opencode uninstall # 卸载(-c 保留配置,-d 保留数据)

二、快速上手

1. 配置模型提供商

在 TUI 中运行 /connect,选择提供商并粘贴 API Key(存储在 ~/.local/share/opencode/auth.json)。新手建议用 OpenCode Zen(官方精选模型,opencode.ai/auth 注册获取 Key);已有订阅可零配置使用 ChatGPT Plus/Pro、GitHub Copilot、GitLab Duo。

2. 初始化项目

1
2
3
cd /path/to/project
opencode
/init # 分析项目并生成 AGENTS.md(建议提交到 Git)

3. 开始对话

  • 提问代码库:这个项目如何处理认证?@packages/functions/src/api/index.ts(用 @ 模糊搜索引用文件,内容自动加入上下文)
  • 添加功能:先按 Tab 切到 Plan 模式(左下角有指示器)描述需求 → 满意后再按 Tab 回到 Build 模式让它实现
  • 撤销/重做:/undo、/redo(依赖 Git 仓库)
  • 分享会话:/share 生成链接复制到剪贴板

三、TUI 界面操作

核心键位(默认 leader 键为 Ctrl+X)

功能 键位
切换主代理(Build/Plan) Tab / Shift+Tab
切换模型变体(推理强度) Ctrl+T
新建会话 Ctrl+X n
会话列表 Ctrl+X l
撤销 / 重做 Ctrl+X u / Ctrl+X r
压缩上下文 Ctrl+X c
模型列表 Ctrl+X m / Ctrl+A
主题列表 Ctrl+X t
代理列表 Ctrl+X a
命令面板 Ctrl+P
编辑器写消息 Ctrl+X e
导出会话 Ctrl+X x
退出 Ctrl+X q 或 Ctrl+C / Ctrl+D
子会话导航 主代理调子代理后:Ctrl+X ↓ 进入,←/→ 切换,↑ 返回
多行输入 Shift+Enter

内置斜杠命令(/ 开头)

/connect(连接提供商)、/init(生成 AGENTS.md)、/compact(压缩上下文)、/details(切换工具执行细节)、/editor(外部编辑器写消息)、/export(导出 Markdown)、/help、/models、/new、/redo、/sessions、/share、/unshare、/themes、/thinking(显示思考块)、/undo、/exit。

其他技巧

  • ! 前缀执行 shell 命令:!ls -la,输出会作为工具结果加入对话
  • 拖拽图片进终端可附加图片参考
  • 命令面板(Ctrl+P)可切换自动批准权限、隐藏用户名等持久化设置

四、CLI 命令(非交互式)

命令 用途
opencode 启动 TUI(-c 继续上次会话,-s ID 指定会话,-m 指定模型,--auto 自动批准权限)
opencode run "..." 非交互模式直接提问(脚本/自动化);-f 附加文件,--format json 输出 JSON 事件
opencode agent create 交互式创建自定义代理
opencode auth login/list/logout 管理提供商凭据
opencode models [provider] 列出可用模型(--refresh 刷新缓存,--verbose 显示成本)
opencode mcp add/list/auth 管理 MCP 服务器
opencode session list/delete 管理会话
opencode stats Token 用量与成本统计(--days、--tools、--models)
opencode export/import 导出/导入会话 JSON(--sanitize 脱敏)
opencode serve / opencode web 无头服务器 / Web 界面(可用 OPENCODE_SERVER_PASSWORD 开启基本认证)
opencode attach <url> 用 TUI 连接远程 opencode 后端
opencode pr <number> 检出 GitHub PR 分支并运行
opencode plugin <module> 安装插件
opencode github install/run 安装/运行 GitHub Agent(仓库自动化)
opencode acp 启动 ACP(Agent Client Protocol)服务器
opencode db path 查看数据库路径
opencode debug 调试与排障工具

五、配置文件

配置文件位置与优先级(后加载的覆盖先加载的)

  1. 远程配置(组织的 .well-known/opencode)
  2. 全局配置 ~/.config/opencode/opencode.json
  3. 自定义路径(OPENCODE_CONFIG 环境变量)
  4. 项目配置 opencode.json(在项目根目录)
  5. .opencode/ 目录(agents、commands、plugins、skills 等)
  6. 内联配置(OPENCODE_CONFIG_CONTENT)
  7. 托管配置(macOS /Library/Application Support/opencode/、Linux /etc/opencode/)

配置是合并而非替换;支持 JSON / JSONC,schema 在 opencode.ai/config.json(TUI 用 opencode.ai/tui.json)。

常用配置项(opencode.json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5", // 主模型 provider/model
"small_model": "anthropic/claude-haiku-4-5", // 轻量任务(标题生成等)
"default_agent": "plan",
"subagent_depth": 1, // 子代理嵌套深度
"autoupdate": true, // 自动更新,可设 "notify"
"share": "manual", // manual | auto | disabled
"snapshot": true, // 文件变更快照(undo 依赖)
"formatter": true, // 代码格式化
"lsp": true, // LSP 服务器
"compaction": { "auto": true, "prune": false, "reserved": 10000 },
"instructions": ["CONTRIBUTING.md", ".cursor/rules/*.md"],
"enabled_providers": ["anthropic", "openai"],
"disabled_providers": ["gemini"],
"plugin": ["opencode-helicone-session"],
"permission": { "edit": "ask", "bash": "ask" },
"provider": {
"anthropic": {
"options": { "baseURL": "https://...", "apiKey": "{env:ANTHROPIC_API_KEY}", "timeout": 600000 }
}
},
"server": { "port": 4096, "hostname": "0.0.0.0" },
"shell": "pwsh"
}

变量替换

  • 环境变量:{env:ANTHROPIC_API_KEY}
  • 文件内容:{file:~/.secrets/openai-key}、{file:./prompts/build.txt}

六、模型与提供商

配置提供商

  1. /connect 选择提供商并填 Key(或设置对应环境变量,如 DEEPSEEK_API_KEY、OPENAI_API_KEY)
  2. /models 选择模型
  3. 可在配置中用 blacklist / whitelist 过滤模型列表,用 baseURL 指向代理/自建端点

本地模型(OpenAI 兼容协议)

支持 Ollama、LM Studio、llama.cpp、Atomic Chat 等:

1
2
3
4
5
6
7
8
9
10
{
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": { "baseURL": "http://localhost:11434/v1" },
"models": { "llama2": { "name": "Llama 2" } }
}
}
}

本地小模型注意:工具调用不好用时可调大 Ollama 的 num_ctx(16k-32k)。

常用提供商速查

  • Anthropic / OpenAI:/connect 后可选订阅 OAuth 登录或手动填 API Key
  • DeepSeek / Moonshot / Groq / Cerebras / OpenRouter 等:平台申请 Key → /connect → /models
  • Amazon Bedrock:支持 IAM Key、AWS_PROFILE、Bearer Token
  • Azure OpenAI:/connect 填 Key + 设置 AZURE_RESOURCE_NAME 环境变量

七、Agents(代理)

OpenCode 用不同类型的代理分工协作:

内置代理

代理 类型 用途
build primary(默认) 全工具可用,日常开发
plan primary 只读规划:编辑与 bash 默认 ask,分析代码不落地修改
general subagent 通用研究、多步任务,可并行执行
explore subagent 快速只读探索代码库
scout subagent 只读外部文档/依赖源码调研

另有隐藏系统代理:compaction(压缩)、title(标题)、summary(摘要)。

使用方式

  • Tab 切换主代理;消息中 @explore、@general 等直接调用子代理
  • 子代理工作在新会话中,用 ←/→ 切换子会话、↑ 返回主会话

自定义代理

两种方式:opencode agent create 交互式生成,或写 Markdown 文件(.opencode/agents/ 或 ~/.config/opencode/agents/):

1
2
3
4
5
6
7
8
9
10
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
edit: deny
bash: deny
---
你是代码审查专家,关注安全、性能、可维护性,只提建议不修改代码。

常用选项:description(必填)、mode(primary/subagent/all)、model、temperature、steps(最大迭代步数)、prompt、permission、hidden、color、top_p;其余参数会直接透传给提供商(如 reasoningEffort)。


八、权限系统

默认全部放行,可配置为 allow / ask / deny:

1
2
3
4
5
6
7
8
9
10
11
{
"permission": {
"*": "ask",
"bash": {
"*": "ask",
"git *": "allow",
"rm *": "deny"
},
"edit": { "*": "deny", "src/**": "allow" }
}
}
  • 规则匹配:支持 *(任意多字符)、?(单字符),最后匹配的规则生效,所以通配放前面、具体规则放后面
  • 关键权限键:read、edit(覆盖 edit/write/patch)、bash、glob、grep、task(子代理)、skill、lsp、webfetch、websearch、external_directory(工作目录外路径,默认 ask)、doom_loop(重复工具调用防护,默认 ask)
  • 安全默认:.env 文件默认禁止读取
  • ask 弹窗选项:once(仅本次)/ always(本次会话内)+ 建议模式 / reject
  • 自动模式:opencode --auto 自动批准未显式 deny 的请求
  • 每代理覆盖:agent 的 permission 优先级高于全局配置

九、自定义命令(重复任务)

在 .opencode/commands/ 或 ~/.config/opencode/commands/ 下建 xxx.md,文件名即命令名:

1
2
3
4
5
6
7
---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---
Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

TUI 中执行 /test。模板支持特殊语法:

  • $ARGUMENTS、$1/$2…:命令行参数
  • !`npm test`:嵌入 shell 命令输出
  • @src/components/Button.tsx:引用文件
  • 自定义命令可覆盖内置命令

十、其他重要功能

  • Rules / AGENTS.md:/init 生成,项目级规则(也可用 instructions 配置项引用多个规则文件)
  • MCP 服务器:opencode mcp add 或配置 "mcp": {}(local/remote 类型),opencode mcp list 查看状态
  • Skills:.opencode/skills/ 定义可复用技能
  • 主题:/themes 选择,或 tui.json 中 "theme": "tokyonight"
  • GitHub 集成:opencode github install 在仓库安装 GitHub Actions 工作流,支持自动化 issue/PR
  • IDE:可安装 IDE 扩展在编辑器内使用
  • Web/远程:opencode web 起 Web 界面;opencode serve + opencode attach 远程连接
  • 统计:opencode stats 查看各项目/模型的 token 成本

十一、环境变量速查

常用:OPENCODE_CONFIG(自定义配置路径)、OPENCODE_TUI_CONFIG、OPENCODE_CONFIG_DIR、OPENCODE_SERVER_PASSWORD(server 认证)、OPENCODE_PERMISSION(内联权限)、OPENCODE_MODELS_URL、EDITOR(/editor、/export 用,GUI 编辑器需带 --wait)。


十二、实用建议

  1. 详细描述需求:像对初级同事说话一样给足上下文和示例;大任务先切 Plan 模式出方案再实现
  2. 善用 @ 引用文件,避免代理猜错代码位置
  3. 善用子代理:@explore 查代码、@general 并行干活,保持主上下文干净
  4. /undo 依赖 Git,项目记得 git init;AGENTS.md 提交进仓库
  5. 控制成本:opencode stats 看用量;用 small_model 跑轻量任务;steps 限制代理迭代
  6. TUI 体验:tui.json 可开 attention(通知+音效)、调滚动速度;用 Ctrl+X h 打开快捷键帮助
  7. 遇到问题:opencode debug、--print-logs、或查看 https://opencode.ai/troubleshooting;社区在 Discord

官方文档:https://opencode.ai/docs(含中文版),GitHub:https://github.com/anomalyco/opencode