opencode-expert

OpenCode 专家指南

OpenCode——这款开源 AI 编码 Agent 的综合指南。

快速参考

任务	命令/操作
启动 TUI	opencode
继续会话	opencode -c 或 opencode --continue
以非交互模式运行	opencode run "message"
启动无头服务	opencode serve
Web 界面	opencode web
切换 Agent	Tab 键
搜索文件	输入 @，然后键入文件名
撤销更改	/undo
重做更改	/redo
分享对话	/share
初始化项目	/init
配置 API 密钥	/connect

Agent

OpenCode 有两个主要 Agent，可通过 Tab 切换：

Build Agent（默认）

• 拥有所有工具的完整访问权限
• 可以编辑文件、运行命令和进行更改
• 用于主动开发工作

Plan Agent

• 只读模式，用于分析和探索
• 编辑文件和运行 bash 命令需要批准（ask 模式）
• 用于在更改前审查实施策略

子 Agent

使用 @ 提及来调用子 Agent：

• @general - 具备完整工具访问权限，可执行复杂研究和多步骤任务
• @explore - 快速只读搜索代码库并解答代码相关问题

键盘快捷键

键	操作
Tab	在 Build 和 Plan Agent 之间切换
@	模糊文件搜索
Ctrl+C	取消当前操作

斜杠命令

命令	说明
/connect	配置 LLM 提供商 API 密钥
/init	初始化项目并创建 AGENTS.md
/undo	撤销近期更改（可连续撤销）
/redo	恢复已撤销的更改
/share	创建可分享的对话链接

CLI 命令

交互模式

# Start TUI in current directory
opencode

# Start in specific project
opencode /path/to/project

# Continue previous session
opencode --continue
opencode -c

# Use specific session
opencode --session <id>
opencode -s <id>

# Start with specific model
opencode --model <model>
opencode -m <model>

# Start with specific agent
opencode --agent build
opencode --agent plan

非交互模式

# Run single prompt
opencode run "Fix the bug in auth.py"

# Run with file attachment
opencode run "Review this" --file README.md
opencode run "Review this" -f README.md

# Run and share result
opencode run "Explain this code" --share

# Run specific command
opencode run --command "npm test"

服务模式

# Start headless API server
opencode serve

# With custom port
opencode serve --port 3000

# With mDNS discovery
opencode serve --mdns

# Web interface
opencode web

管理命令

# Authentication
opencode auth login
opencode auth list
opencode auth logout

# Models
opencode models              # List available models
opencode models --refresh    # Refresh model cache

# Agents
opencode agent create        # Create custom agent
opencode agent list          # List agents

# MCP servers
opencode mcp add <server>
opencode mcp list
opencode mcp auth
opencode mcp debug

# Sessions
opencode session list
opencode session list -n 10  # Last 10 sessions

# Statistics
opencode stats
opencode stats --days 7
opencode stats --tools
opencode stats --models

# Export/Import
opencode export <sessionID>
opencode import <file>

# Upgrade
opencode upgrade
opencode upgrade <version>

内置工具

OpenCode 为 Agent 提供以下工具：

工具	说明
read	读取文件内容，可选指定行范围
write	创建新文件或覆盖现有文件
edit	使用精确的字符串替换来修改文件
patch	应用补丁文件
grep	使用正则表达式搜索文件内容
glob	按模式查找文件（**/*.js）
list	列出文件和目录
bash	执行 shell 命令
lsp	语言服务器协议集成（实验性）
todowrite	创建/更新任务列表
todoread	读取当前待办状态
skill	将技能文件载入对话
webfetch	获取并阅读网页
question	向用户提出澄清问题

技能

文件位置

技能按以下顺序从这些位置发现：

1. .agents/skills/<name>/SKILL.md（项目级，与 Codex 共享）
2. .claude/skills/<name>/SKILL.md（兼容 Claude 的项目级技能）
3. ~/.config/opencode/skills/<name>/SKILL.md（全局）
4. ~/.claude/skills/<name>/SKILL.md（兼容 Claude 的全局技能）

技能格式

---
name: my-skill
description: Description of what this skill does and when to use it.
---

# Skill Content

Instructions and documentation here...

名称规则

• 使用小写字母数字字符，单个连字符可用于分隔
• 不能以连字符开头或结尾
• 不能包含连续连字符（--）
• 必须与目录名称一致

配置

配置位置

• 项目级：.opencode/ 或 opencode.json
• 全局：~/.config/opencode/

环境变量

变量	说明
OPENCODE_CONFIG	自定义配置路径
OPENCODE_PERMISSION	权限模式
OPENCODE_SERVER_PASSWORD	服务身份验证密码
OPENCODE_DISABLE_AUTOUPDATE	禁用自动更新
OPENCODE_EXPERIMENTAL	启用实验性功能
OPENCODE_ENABLE_EXA	启用 Exa 搜索

自定义 Agent

通过 opencode agent create 创建 Agent，或在以下位置定义：

• opencode.json
• ~/.config/opencode/agents/
• .opencode/agents/

Agent 配置选项：描述、温度、模型、工具权限、系统提示词。

最佳实践

先使用 Plan 模式

切换到 Plan Agent（Tab），在进行更改前审查实施策略。

文件引用

在提示词中使用 @filename 模糊搜索并引用文件。

撤销栈

放心使用 /undo，更改会按顺序堆叠，并且可以通过 /redo 还原。

会话管理

使用 --continue 或 -c 恢复之前的会话并延续上下文。

参考资料

详细文档请参阅：

• references/cli.md - 完整的 CLI 参考
• references/tools.md - 工具详情和权限
• references/agents.md - Agent 配置指南