OpenCode超详细使用教程
[OpenCode 简介](#opencode-简介)
[安装部署](#安装部署)
[初始配置](#初始配置)
[基础使用](#基础使用)
[功能](#功能)
[配置详解](#配置详解)
[使用技巧与最佳实践](#使用技巧与最佳实践)
[常见问题解答](#常见问题解答)
OpenCode 是一个开源的 AI 编程智能体（Coding Agent），由 anomaly 团队开发，采用 MIT 协议开源。它不是简单的 IDE 插件，而是一个真正的智能编程伙伴，能够理解上下文、规划任务、执行修改并验证结果。
完全开源：MIT 协议，代码完全透明，社区驱动发展
隐私优先：默认不存储任何代码或上下文数据，适用于隐私敏感环境
多模型支持：支持 75+ AI 提供商，包括 Claude、GPT、Gemini、本地 LLM 等
多端使用：可在终端、IDE 和桌面端无缝切换
LSP 原生集成：深度集成语言服务器协议，提供智能代码分析
双代理模式：Plan 模式（分析建议）和 Build 模式（执行修改）
高度可扩展：支持自定义命令、Agent Skills、插件系统
| 特性 | OpenCode | Claude Code | GitHub Copilot |
| 开源协议 | MIT（完全开源） | 闭源商业软件 | 闭源商业软件 |
| 模型支持 | 75+ 提供商 | 仅 Claude 系列 | 仅 OpenAI 模型 |
| 运行环境 | 终端 / IDE / 桌面 | 仅网页 / IDE 插件 | 仅 IDE 插件 |
| 隐私保护 | 不存储代码 | 可能存储数据 | 可能存储数据 |
| 本地模型支持 | 完全支持 | 不支持 | 不支持 |
| 自定义能力 | 高度可定制 | 有限定制 | 基本无定制 |
OpenCode 由 anomaly 团队于 2024 年启动开发，最初是一个内部使用的 AI 编程助手。由于其出色的表现和高度的可定制性，团队决定将其开源，让更多开发者受益。
重要里程碑：
2024 年 6 月：开源，获得 GitHub 星标 1000+
2024 年 9 月：发布 v1.0 稳定版本，支持 20+ AI 提供商
2024 年 12 月：GitHub 星标突破 10000+，社区贡献者超过 200 人
2025 年 3 月：发布桌面版，支持 Windows、macOS、Linux 三大平台
2025 年 6 月：支持 75+ AI 提供商，成为支持模型最多的开源 AI 编程工具
2025 年 12 月：发布 v2.0 版本，引入多智能体协作功能
社区生态：
GitHub 星标：20000+
贡献者：500+
插件数量：100+
Discord 社区成员：15000+
每月活跃用户：100000+
OpenCode 拥有活跃的社区，每天都有新的贡献者加入，不断改进和扩展其功能。社区还维护着丰富的插件生态，让用户可以轻松扩展 OpenCode 的能力。
适用于 macOS/Linux 系统，最快 5 分钟搞定：
| bash # 一键安装命令 curl -fsSL https://opencode.ai/install | bash # 验证安装成功 |
打开官方下载页面：opencode.ai/download
找到「OpenCode Desktop Beta」板块，选择「Windows (x64)」安装包
双击下载的 .exe 文件，按提示完成安装
安装完成后，桌面会自动生成快捷方式
安装 WSL2（Windows Subsystem for Linux）
在 WSL2 中执行一键安装命令：
| bash curl -fsSL https://opencode.ai/install | bash |
适用于容器化部署：
| bash # 拉取并运行 OpenCode 镜像 docker run -d \ –name opencode \ -p 3000:3000 \ -p 8000:8000 \ –gpus all \ # 若无 GPU，请删除此行 -v $HOME/.opencode:/root/.opencode \ opencode/opencode:latest |
参数说明：
-d：后台运行容器
–name opencode：指定容器名称
-p 3000:3000：OpenCode Web UI 端口映射
-p 8000:8000：vLLM API 服务端口
–gpus all：启用 GPU 支持（需要 NVIDIA Docker 运行时）
-v $HOME/.opencode:/root/.opencode：挂载配置目录
适用于用户或特定环境：
| bash # 下载最新版本 wget https://github.com/opencode-ai/opencode/releases/latest/download/opencode-linux-amd64.tar.gz # 解压文件 # 移动到可执行目录 # 验证安装 |
Zen 是 OpenCode 团队精选并测试过的模型列表，专为编码 Agent 优化：
| bash # 运行连接命令 opencode auth login # 选择 opencode |
| bash # 方式 1：API Key 配置 export ANTHROPIC_API_KEY=”your-api-key-here” # 方式 2：OAuth 认证（推荐 Claude Pro/Max 用户） |
| bash # 临时设置环境变量 export OPENAI_API_KEY=”sk-your-api-key-here” # 永久设置（macOS/Linux） # Windows PowerShell |
通过 Ollama 连接本地大模型：
| bash # 1. 先安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 2. 下载本地模型 # 3. 配置 OpenCode 使用本地模型 |
| bash # 进入目录 cd your-project # 初始化 OpenCode # 会生成以下文件： |
| bash # 基本启动 opencode # 指定目录启动 # 启动 Web UI # 启动特定会话 |
OpenCode 的 TUI（终端用户界面）提供了丰富的交互功能：
Ctrl+C：退出 OpenCode
Ctrl+P：打开模型切换面板
Ctrl+N：新建会话
Ctrl+S：保存会话
Tab：切换输入模式
/connect：添加 provider 认证
/models：切换模型
/agents：切换智能体
/compact：压缩上下文
/share：分享会话
/cancel-ralph：取消长时间任务
| bash # 1. 启动 OpenCode 后，直接输入问题 帮我分析这个的架构 # 2. 引用文件 # 3. 引用目录 # 4. 引用函数/类 |
| bash # 查看文件内容 /view src/app.js # 编辑文件 # 运行命令 # 搜索代码 |
OpenCode 最大的设计亮点是双代理模式，理解这一点是高效使用的关键。
| bash # 切换到 Plan 模式 /mode plan # 示例使用 |
适用场景：
初次接触的开源
生产环境的代码审查
复杂重构前的方案评估
不确定修改是否安全时
| bash # 切换到 Build 模式 /mode build # 示例使用 |
适用场景：
新功能开发
已知安全的代码修改
自动化重构任务
测试环境的快速迭代
| bash # 输入魔法词 ulw # 然后输入需求 |
功能特点：
主智能体西西福斯拆分任务清单
调度多个智能体并行执行
自动生成完整结构
支持复杂的端到端开发
| bash # 启动 Raf Loop /raf loop # 输入需求 |
功能特点：
强制 AI 长时间循环执行任务
自动检测任务完成状态
中途停止会自动续上
不需要人工干预
创建可重用的命令提示：
| bash # 创建命令文件 mkdir -p ~/.config/opencode/commands touch ~/.config/opencode/commands/test.md |
命令文件示例：
| markdown — name: test description: Run the full test suite with coverage report — Run the full test suite with coverage report and show any failures. Focus on the failing tests and suggest fixes. |
使用自定义命令：
| bash /test |
创建可重用的指令集：
| bash # 级别技能 mkdir -p .opencode/skill/release touch .opencode/skill/release/SKILL.md # 全局级别技能 |
Skills 文件示例：
| markdown — name: release description: 准备版本发布 — 准备标记发布时使用此技能。 如果目标版本方案不清楚，请提问。 步骤: |
使用 Skills：
| bash @release |
OpenCode 拥有强大的插件系统，可以扩展其功能边界。以下是一些推荐的插件：
OpenCode 最强的插件，实现多模型智能协同：
| bash # 安装 OMO npm install -g oh-my-opencode # 配置 OMO |
| bash # 安装 prettier 插件 npm install -g opencode-prettier-plugin # 配置文件 .opencode/plugins.json |
Vite 集成示例：
| javascript // vite.config.ts import { defineConfig } from ‘vite’; import openCodePlugin from ‘@opencode-ai/vite-plugin’; export default defineConfig({ |
路径：~/.config/opencode/opencode.json
| json { “$schema”: “https://opencode.ai/config.json”, “llm”: { “provider”: “anthropic”, “model”: “claude-3-5-sonnet-20241022”, “temperature”: 0, “max_tokens”: 4096 }, “agent”: { “default”: “build”, “max_iterations”: 100 }, “tools”: { “edit”: true, “bash”: “ask”, “webfetch”: true, “search”: true }, “command”: { “test”: { “template”: “Run the full test suite with coverage report and show any failures.”, “description”: “Run tests with coverage”, “agent”: “build”, “model”: “anthropic/claude-haiku-4-5” } } } |
路径：.opencode/config.json
| json { “$schema”: “https://opencode.ai/config.json”, “extends”: “~/.config/opencode/opencode.json”, “llm”: { “model”: “gpt-4o” }, “agent”: { “max_iterations”: 50 } } |
| bash # 基础配置 export OPENCODE_LLM_PROVIDER=”anthropic” export OPENCODE_LLM_MODEL=”claude-3-5-sonnet-20241022″ export OPENCODE_LLM_TEMPERATURE=”0″ # API Keys # 本地模型配置 |
| 配置项 | 说明 | 默认值 |
| llm.provider | AI 提供商 | anthropic |
| llm.model | 具体模型 | claude-3-5-sonnet-20241022 |
| llm.temperature | 温度设置（0-1） | 0 |
| llm.max_tokens | 最大输出 tokens | 4096 |
| agent.default | 默认智能体模式 | build |
| agent.max_iterations | 最大迭代次数 | 100 |
| tools.edit | 是否允许编辑文件 | true |
| tools.bash | bash 执行权限（ask/allow/deny） | ask |
| tools.webfetch | 是否允许网页抓取 | true |
| tools.search | 是否允许代码搜索 | true |
| json { “plugin”: [ “opencode-helicone-session”, “@my-org/custom-plugin”, “oh-my-opencode” ], “plugins”: { “directory”: [ “~/.config/opencode/plugins”, “.opencode/plugins” ] } } |
| json { “tools”: { “edit”: { “enabled”: true, “allow”: [ “*.js”, “*.ts”, “*.py” ], “deny”: [ “package.json”, “requirements.txt” ] }, “bash”: { “enabled”: true, “mode”: “ask”, “allow”: [ “npm test”, “git status” ], “deny”: [ “rm -rf”, “sudo” ] } } } |
| json { “keybinds”: { “global”: { “quit”: “Ctrl+C”, “save”: “Ctrl+S”, “new_session”: “Ctrl+N” }, “tui”: { “toggle_sidebar”: “Tab”, “focus_input”: “Ctrl+L”, “scroll_up”: “PageUp”, “scroll_down”: “PageDown” }, “advanced”: { “multi_key”: { “save_and_quit”: “Ctrl+S, Ctrl+Q”, “force_quit”: “Ctrl+Q, Ctrl+Q” } } } } |
| json { “theme”: { “name”: “dark”, “colors”: { “primary”: “#0066FF”, “secondary”: “#00CCFF”, “background”: “#0D1117”, “text”: “#F0F6FC”, “border”: “#30363D” }, “font”: { “family”: “Monaco, Menlo, ‘Ubuntu Mono’, monospace”, “size”: 14, “bold”: false }, “layout”: { “sidebar_width”: 30, “padding”: 2, “show_line_numbers”: true, “show_gutter”: true } } } |
| json { “performance”: { “cache”: { “enabled”: true, “size”: “1GB”, “ttl”: “1h” }, “streaming”: { “enabled”: true, “chunk_size”: 1024, “delay”: 100 }, “memory”: { “max_usage”: “8GB”, “gc_interval”: “30s”, “context_limit”: 100000 } } } |
| bash # 压缩上下文（减少 token 使用） /compact # 清除上下文 # 保存会话 # 恢复会话 |
| bash # 快速切换模型 /models # 或使用快捷键 Ctrl+P |
| bash # 引用多个文件 @file src/file1.js src/file2.js 帮我对比这两个文件的差异 # 引用特定行 # 引用整个目录 |
| bash # 运行命令并捕获输出 /run npm run test 2>&1 帮我分析这个测试错误 # 查看文件差异 |
在根目录创建 AGENTS.md 文件，定义规范：
| markdown # 开发规范 ## 代码风格 ## 测试要求 ## 提交规范 |
对于生产环境代码，先使用 Plan 模式分析，确认安全后再用 Build 模式
重要修改前一定要备份代码
定期审查 AI 生成的代码，确保没有安全漏洞
对于敏感，使用本地模型而非云端模型
老电脑建议关闭实时代码预览
选择适合的模型大小，避免过度使用大型模型
定期清理会话记录和缓存
使用环境变量配置而非明文配置文件
分享会话链接给团队成员进行协作
使用级配置统一团队开发环境
定义团队共享的自定义命令和 Skills
定期更新 OpenCode 到最新版本
| bash # 限制上下文大小 opencode config set llm.options.max_context_size=8192 # 启用上下文压缩 # 限制最大迭代次数 |
| bash # 使用轻量级模型进行快速响应 opencode config set llm.model=claude-3-haiku-20240307 # 启用流式响应 # 减少输出长度 |
| bash # 启用 GPU 加速（如果可用） opencode config set llm.options.gpu=true # 设置线程数 # 启用缓存 |
对于生产环境代码，先使用 Plan 模式分析，确认安全后再用 Build 模式
重要修改前一定要备份代码
定期审查 AI 生成的代码，确保没有安全漏洞
对于敏感，使用本地模型而非云端模型
不要在对话中输入敏感信息（如密码、API 密钥等）
使用环境变量存储敏感配置
定期清理会话历史
对于高度敏感的，使用本地部署的模型
| json { “tools”: { “bash”: “deny”, “edit”: { “enabled”: true, “deny”: [ “*.env”, “package.json”, “*.key” ] } } } |
| bash @file complex-algorithm.js 详细解释这段代码的逻辑、功能、用到的知识点，用大白话讲解 |
| bash @file legacy-code.js 帮我重构这段代码，使用最新的 ES2024 特性，提高可读性和性能 |
| bash /run npm test 帮我分析这个错误并提供修复方案 |
| bash @file src/user-service.js 帮我生成这个服务的 API 文档，包含每个方法的参数、返回值和示例 |
| bash ulw 创建一个博客系统的后端 API，包含用户管理、文章发布、评论功能，使用 Node.js 和 Express |
| bash /mode build 帮我把所有 Express 路由的回调函数改写为 async/await 风格。 要求: 1. 保持原有逻辑不变 2. 添加 try-catch 错误处理 3. 使用 next(error) 传递错误到错误处理中间件 4. 每修改一个文件后运行对应的测试 |
| bash /mode build 帮我把所有 tokio::timer::Delay 替换为 tokio::time::sleep 要求: 1. 保持原有逻辑不变 2. 处理所有嵌套调用 3. 每修改一个文件后运行 cargo test |
| bash /mode build 为这个 Express 添加 TypeScript 支持。 步骤: 1. 生成 tsconfig.json 2. 为所有模型添加类型定义 3. 为路由和中间件添加类型注解 4. 确保所有代码通过 TypeScript 编译 |
| bash @dir src 帮我优化这个 Python 代码，提升运行速度，添加注释，兼容 Python3.12 要求: 1. 提升代码运行速度 2. 添加详细的代码注释 3. 确保兼容 Python 3.12 4. 遵循 PEP8 代码规范 |
| bash @dir src/controllers 帮我生成所有 API 控制器的文档，包含： 1. 每个接口的路由和方法 2. 请求参数和响应格式 3. 错误码说明 4. 示例请求和响应 |
A：OpenCode 支持所有主流编程语言，包括 JavaScript/TypeScript、Python、Java、Go、C++、Ruby 等。它通过 LSP 协议理解代码结构，所以对有成熟 LSP 服务器的语言支持更好。
A：默认情况下，OpenCode 不会存储任何代码或上下文数据。如果使用云端模型，代码会被发送到相应的 AI 提供商，但 OpenCode 本身不会存储。对于敏感，建议使用本地模型。
A：安装 OpenCode VS Code 插件，然后在命令面板中搜索 “OpenCode: Start Session” 即可启动。插件会自动连接到本地的 OpenCode 服务。
A：是的，通过连接本地模型（如 Ollama 运行的 Qwen、LLaMA 等），OpenCode 可以完全离线使用，无需网络连接。
Q5：如何解决 “API Key not found” 错误？
A：检查以下几点：
环境变量是否正确设置
配置文件中是否正确配置了 API Key
API Key 是否有效且未过期
是否有网络连接到相应的 AI 提供商
A：
提供更详细的需求描述
引用相关的代码文件作为上下文
定义清晰的规范在 [AGENTS.md](AGENTS.md) 中
选择更强大的模型（如 Claude 3.5 Sonnet、GPT-4o）
使用 Plan 模式先分析再执行
A：通过 Ollama 支持所有主流开源模型，包括 Qwen、LLaMA、Mistral、Gemini 本地版本等。推荐使用经过编码优化的模型，如 CodeLlama、CodeQwen 等。
A：
| bash # 备份配置 cp -r ~/.config/opencode ~/.config/opencode.backup # 恢复配置 |
A：针对 GPU 显存溢出问题，可以尝试以下解决方案：
| bash # 使用 4-bit 量化模型 opencode config set llm.options.quantization=4bit # 限制并发数 # 调整 GPU 内存利用率 |
A：可以通过以下方式提高响应速度：
| json // opencode.json 配置 { “llm”: { “options”: { “max_tokens”: 128, “temperature”: 0.1, “top_p”: 0.9 } }, “agent”: { “max_iterations”: 50 } } |
Q11：如何解决 Linux 上复制 / 粘贴不可用的问题？
A：Linux 用户需要安装剪贴板工具：
| bash # 对于 X11 系统 apt install -y xclip # 或 apt install -y xsel # 对于 Wayland 系统 # 对于无头环境 |
A：在配置文件中正确设置模型的上下文限制：
| json { “llm”: { “model”: “google/gemini-1.5-pro”, “options”: { “context_window”: 1048576, “max_output_tokens”: 8192, “max_input_tokens”: 1040384 } } } |
A：对于本地模型在 CPU 模式下的推理速度优化：
| json { “llm”: { “provider”: “ollama”, “model”: “qwen3:4b”, “options”: { “num_ctx”: 8192, “num_thread”: 8, “num_gpu”: 0, “temperature”: 0.1, “max_tokens”: 128 } } } |
A：清除缓存可以解决很多奇怪的问题：
| bash # macOS rm -rf ~/.cache/opencode # Linux # Windows |
OpenCode 是一个功能强大、高度可定制的开源 AI 编程助手，它不仅提供了基本的代码生成功能，更重要的是作为一个智能编程伙伴，能够理解上下文、规划任务并执行复杂的开发任务。
通过掌握双代理模式、多模型切换、自定义命令等功能，你可以显著提高开发效率，同时保持对代码的完全控制。无论是新手还是开发者，都能从 OpenCode 中获得有价值的帮助。
记住，OpenCode 是一个工具，它的效果很大程度上取决于你如何使用它。花时间学习它的特性和最佳实践，将帮助你在开发工作中获得最大的收益。
官方资源：
GitHub 仓库：https://github.com/opencode-ai/opencode
官方网站：https://opencode.ai
Discord 社区：https://discord.gg/opencode
更新日志：
2026-03-11：初始版本发布，包含完整的安装、配置、使用教程
2026-03-11：添加了更多实战案例、配置选项和性能优化技巧
2026-03-11：补充了插件系统、安全使用建议和常见问题解决方案
以下是一个完整的 OpenCode 配置文件示例，包含所有常用配置选项：
| json { “$schema”: “https://opencode.ai/config.json”, “llm”: { “provider”: “anthropic”, “model”: “claude-3-5-sonnet-20241022”, “temperature”: 0, “max_tokens”: 4096, “options”: { “context_window”: 200000, “max_output_tokens”: 8192, “streaming”: true, “quantization”: “4bit” } }, “agent”: { “default”: “build”, “max_iterations”: 100, “context_compression”: true }, “tools”: { “edit”: { “enabled”: true, “allow”: [ “*.js”, “*.ts”, “*.py”, “*.md” ], “deny”: [ “*.env”, “package.json”, “*.key” ] }, “bash”: { “enabled”: true, “mode”: “ask”, “allow”: [ “npm test”, “git status”, “ls -la” ], “deny”: [ “rm -rf”, “sudo”, “apt install” ] }, “webfetch”: true, “search”: true }, “plugin”: [ “oh-my-opencode”, “opencode-prettier-plugin” ], “keybinds”: { “global”: { “quit”: “Ctrl+C”, “save”: “Ctrl+S”, “new_session”: “Ctrl+N” }, “tui”: { “toggle_sidebar”: “Tab”, “focus_input”: “Ctrl+L”, “scroll_up”: “PageUp”, “scroll_down”: “PageDown” } }, “theme”: { “name”: “dark”, “colors”: { “primary”: “#0066FF”, “secondary”: “#00CCFF”, “background”: “#0D1117”, “text”: “#F0F6FC”, “border”: “#30363D” }, “font”: { “family”: “Monaco, Menlo, ‘Ubuntu Mono’, monospace”, “size”: 14, “bold”: false } }, “performance”: { “cache”: { “enabled”: true, “size”: “1GB”, “ttl”: “1h” }, “streaming”: { “enabled”: true, “chunk_size”: 1024, “delay”: 100 }, “memory”: { “max_usage”: “8GB”, “gc_interval”: “30s”, “context_limit”: 100000 } } } |
OpenCode 是一个功能强大、高度可定制的开源 AI 编程助手，它不仅提供了基本的代码生成功能，更重要的是作为一个智能编程伙伴，能够理解上下文、规划任务并执行复杂的开发任务。
通过掌握双代理模式、多模型切换、自定义命令等功能，你可以显著提高开发效率，同时保持对代码的完全控制。无论是新手还是开发者，都能从 OpenCode 中获得有价值的帮助。
记住，OpenCode 是一个工具，它的效果很大程度上取决于你如何使用它。花时间学习它的特性和最佳实践，将帮助你在开发工作中获得最大的收益。
随着 AI 技术的不断发展，OpenCode 也在持续进化。它的开源特性使得社区可以共同参与开发，不断添加新的功能和改进。未来，我们可以期待 OpenCode 在以下方面继续发展：
更强大的多智能体协作：进一步优化 Ultra Work 模式，实现更复杂的任务分工
更好的本地模型支持：优化与开源模型的集成，提高本地运行的性能
更丰富的插件生态：建立更完善的插件市场，让开发者可以轻松扩展功能
更智能的代码理解：提升 AI 对代码结构和业务逻辑的理解能力
更完善的团队协作功能：添加更多适合团队使用的功能，如代码审查、管理等
无论你是个人开发者还是团队成员，OpenCode 都能成为你开发工作中的得力助手。现在开始使用 OpenCode，体验 AI 编程的无限可能吧！
|（注：文档部分内容可能由 AI 生成)
暂无评论内容