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 | opencode upgrade # 升级到最新版 |
二、快速上手
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 | cd /path/to/project |
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 |
调试与排障工具 |
五、配置文件
配置文件位置与优先级(后加载的覆盖先加载的)
- 远程配置(组织的
.well-known/opencode) - 全局配置
~/.config/opencode/opencode.json - 自定义路径(
OPENCODE_CONFIG环境变量) - 项目配置
opencode.json(在项目根目录) .opencode/目录(agents、commands、plugins、skills 等)- 内联配置(
OPENCODE_CONFIG_CONTENT) - 托管配置(macOS
/Library/Application Support/opencode/、Linux/etc/opencode/)
配置是合并而非替换;支持 JSON / JSONC,schema 在
opencode.ai/config.json(TUI 用opencode.ai/tui.json)。
常用配置项(opencode.json)
1 | { |
变量替换
- 环境变量:
{env:ANTHROPIC_API_KEY} - 文件内容:
{file:~/.secrets/openai-key}、{file:./prompts/build.txt}
六、模型与提供商
配置提供商
/connect选择提供商并填 Key(或设置对应环境变量,如DEEPSEEK_API_KEY、OPENAI_API_KEY)/models选择模型- 可在配置中用
blacklist/whitelist过滤模型列表,用baseURL指向代理/自建端点
本地模型(OpenAI 兼容协议)
支持 Ollama、LM Studio、llama.cpp、Atomic Chat 等:
1 | { |
本地小模型注意:工具调用不好用时可调大 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 | --- |
常用选项:description(必填)、mode(primary/subagent/all)、model、temperature、steps(最大迭代步数)、prompt、permission、hidden、color、top_p;其余参数会直接透传给提供商(如 reasoningEffort)。
八、权限系统
默认全部放行,可配置为 allow / ask / deny:
1 | { |
- 规则匹配:支持
*(任意多字符)、?(单字符),最后匹配的规则生效,所以通配放前面、具体规则放后面 - 关键权限键:
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 | --- |
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)。
十二、实用建议
- 详细描述需求:像对初级同事说话一样给足上下文和示例;大任务先切 Plan 模式出方案再实现
- 善用
@引用文件,避免代理猜错代码位置 - 善用子代理:
@explore查代码、@general并行干活,保持主上下文干净 - /undo 依赖 Git,项目记得
git init;AGENTS.md 提交进仓库 - 控制成本:
opencode stats看用量;用small_model跑轻量任务;steps限制代理迭代 - TUI 体验:
tui.json可开attention(通知+音效)、调滚动速度;用Ctrl+X h打开快捷键帮助 - 遇到问题:
opencode debug、--print-logs、或查看 https://opencode.ai/troubleshooting;社区在 Discord
官方文档:https://opencode.ai/docs(含中文版),GitHub:https://github.com/anomalyco/opencode