01-OpenCode 快速上手

01-OpenCode 快速上手本指南帮助你在 30 分钟内掌握 OpenCode 的基本使用。一、OpenCode 简介1.1 什么是 OpenCodeOpenCode 是一款开源的 AI 编程助手 CLI 工具通过自然语言命令与 AI 进行交互帮助开发者高效完成代码编写、重构、测试等任务。1.2 核心特点自然语言交互用日常语言描述需求AI 自动执行批量文件操作同时处理多个文件提高效率项目级上下文理解整个代码库提供精准建议可扩展性强支持 MCP、Plugin、Agent 等扩展机制1.3 适用场景场景说明项目初始化快速搭建项目结构、配置文件批量重构跨文件修改、代码迁移代码生成根据需求自动生成代码测试编写自动生成单元测试、集成测试代码审查批量检查代码质量二、安装与配置2.1 环境要求Node.js 18Git2.2 Windows 安装方式一通过 npm 安装推荐步骤 1检查 Node.js 环境# 检查 Node.js 版本node--version# 确保版本 18步骤 2安装 OpenCode# 全局安装 OpenCodenpm install-g opencode-ai步骤 3验证安装# 查看帮助opencode--help方式二使用 npx 直接运行无需安装# 使用 npx 运行无需全局安装npx opencode-ai方式三通过 Git 安装最新开发版# 克隆仓库git clone https://github.com/opencode-ai/opencode.git# 进入目录cd opencode# 安装依赖npm install# 链接到全局npm link方式四使用独立安装包访问官方 releases 页面下载 Windows 安装包解压到自定义目录如C:\tools\opencode将该目录添加到系统环境变量 PATH添加环境变量步骤# 以管理员身份运行 PowerShell执行[Environment]::SetEnvironmentVariable(Path,[Environment]::GetEnvironmentVariable(Path,User);C:\tools\opencode,User)Windows 常见问题问题 1‘opencode’ 不是内部或外部命令解决方法# npm 全局安装目录可能不在 PATH 中# 先找到 npm 全局安装路径npm config get prefix# 将返回的路径添加到 PATH例如 C:\Users\用户名\AppData\Roaming\npm$npmPath npm config get prefix[Environment]::SetEnvironmentVariable(Path,[Environment]::GetEnvironmentVariable(Path,User);$npmPath,User)# 或使用 npx 直接运行npx opencode-ai问题 2安装时报权限错误解决方法# 使用管理员权限运行 PowerShell 后重新安装npm install-g opencode-ai问题 3Node.js 版本过低解决方法# 检查 Node.js 版本node--version# 如果未安装或版本过低从 https://nodejs.org 下载安装 LTS 版本# 或使用 winget 安装winget install OpenJS.NodeJS.LTS2.3 初始配置配置文件位置~/.opencode/config.json # 全局配置基础配置示例{provider:{default:anthropic,anthropic:{api_key:your-api-key-here}}}配置说明provider.default设置默认 AI 提供商provider.name.api_key各提供商的 API 密钥支持的提供商包括 anthropic、openai、google 等三、基础命令3.1 启动 OpenCode# 启动并进入交互模式默认 TUIopencode# 在指定项目目录启动opencode /path/to/project3.2 常用 CLI 命令命令功能示例opencode启动 TUI 交互模式opencodeopencode run message执行单条消息后退出opencode run 解释 main.pyopencode --continue/-c继续上次会话opencode -copencode --session id/-s id打开指定会话opencode -s abc123opencode --model provider/model/-m指定模型opencode -m anthropic/claude-sonnet-4-20250514opencode web启动 Web 界面opencode webopencode serve启动服务模式opencode serveopencode upgrade升级到最新版本opencode upgradeopencode stats查看使用统计opencode statsopencode --help查看帮助opencode --help3.3 会话管理命令命令功能opencode session list列出所有会话opencode session delete id删除指定会话opencode export [sessionID]导出会话opencode import file导入会话3.4 扩展管理命令命令功能opencode mcp add/list/auth/logout/debugMCP 服务器管理opencode providers管理 AI 提供商和凭证opencode agent create/listAgent 管理opencode plugin module安装插件opencode githubGitHub 集成opencode pr number查看/处理 PR3.5 TUI 交互命令命令功能/help显示帮助信息/status查看当前状态/clear清除对话历史/compact压缩历史记录/exit退出3.6 第一个会话示例$ opencode OpenCode v1.3.17 Type /helpforhelp, /exit toexit你好我想创建一个 Python 项目 你好我来帮你创建一个 Python 项目。 请告诉我1. 项目类型Web API / CLI 工具 / 数据分析 / 其他2. 项目名称3. 主要功能需求Web API项目名 fastapi-demo需要用户认证和 CRUD 操作 好的我来为你创建 fastapi-demo 项目。[OpenCode]: 创建项目目录结构...[OpenCode]: 生成配置文件...[OpenCode]: 创建基础代码... ✓ 项目已创建fastapi-demo/ 目录结构 fastapi-demo/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── models/ │ ├── routers/ │ └── utils/ ├── tests/ ├── requirements.txt └── README.md 接下来我可以帮你 - 设计数据库模型 - 实现认证模块 - 创建 API 路由 - 编写测试代码 你想从哪一步开始/exit 再见四、工作模式4.1 交互模式默认模式进入持续对话opencode你的指令4.2 单次命令模式执行单个命令后退出opencode run分析 src/ 目录的代码质量4.3 其他常用选项选项功能--pure纯净模式启动--print-logs打印日志输出--log-level设置日志级别--port指定服务端口--hostname指定主机名--mdns启用 mDNS 发现--fork分叉模式五、常用操作示例5.1 文件操作# 读取文件读取 app/main.py 文件内容# 修改文件在 app/main.py 中添加健康检查路由# 创建文件创建 tests/test_auth.py 文件编写认证测试5.2 代码生成# 生成模型创建 User 模型包含 id、username、email、password_hash 字段# 生成路由为 User 模型生成 CRUD API 路由# 生成测试为 app/routers/users.py 生成 pytest 测试5.3 批量操作# 批量修改将所有文件中的 print 语句改为 logging# 批量生成为所有模型生成对应的 schemas六、上下文管理6.1 查看当前上下文/status 当前上下文 - 工作目录: /home/user/project - 当前模型: claude-sonnet-4-20250514 - 对话长度:15轮 - 已加载文件: app/main.py, app/models/user.py6.2 管理对话历史# 清除历史保留系统提示/clear# 压缩历史保留关键信息/compact# 查看历史摘要总结我们的对话历史6.3 引用文件和代码# 引用文件分析 app/main.py 中的路由配置# 引用符号解释 UserModel 的用途# 引用目录检查 src/ 目录的结构七、安全与确认7.1 危险操作确认OpenCode 会在执行以下操作前要求确认删除文件修改多个文件批量操作执行系统命令Git 提交和推送删除所有 .pyc 文件 ⚠️ 这将删除以下文件 - app/__pycache__/main.cpython-39.pyc - app/__pycache__/models.cpython-39.pyc 确认执行(y/n): y ✓ 已删除2个文件7.2 权限管理OpenCode 在 TUI 交互模式下通过内置的权限提示机制处理敏感操作。当 AI 尝试执行可能影响文件系统的操作如写入文件、执行命令等时会在界面中弹出确认提示用户可以选择允许或拒绝。无需额外的配置文件来设置自动确认规则。八、快捷键与技巧8.1 命令行快捷键快捷键功能Tab自动补全↑/↓浏览历史命令CtrlC中断当前操作CtrlD退出同 /exit8.2 提高效率的技巧使用简洁指令# 好的示例修复 app/models.py 中的类型错误# 避免冗长描述请帮我看看这个文件里有什么类型错误然后修复一下...分步执行复杂任务第一步设计数据库模型第二步生成 SQLAlchemy 代码第三步创建迁移脚本利用上下文# 第一次详细说明创建 User 模型包含以下字段...# 后续可以简化为 User 添加 email 验证九、故障排除9.1 常见问题Q: 启动后无响应# 检查日志opencode --print-logs# 重置配置mv~/.opencode/config.json ~/.opencode/config.json.bakQ: AI 响应慢# 压缩历史/compact# 或清除历史重新开始/clearQ: 文件操作失败# 检查权限ls-la/path/to/project# 使用 sudo谨慎sudoopencode /path/to/project9.2 获取帮助# 查看帮助opencode--help# 在交互模式中/help# 查看调试信息opencode debug十、下一步现在你已经掌握了 OpenCode 的基础使用建议继续学习02-CLI交互技巧.md - 提升交互效率03-MCP与工具调用.md - 扩展工具能力09-实战PythonWebAPI开发.md - 完整项目实战文档版本: 1.0 | 建议学习时长: 30分钟