opencode-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenCode Expert

OpenCode 专家指南

Comprehensive guide for OpenCode - the open-source AI coding agent.

这是开源AI编码Agent OpenCode的全面使用指南。

Quick Reference

快速参考

Task	Command/Action
Start TUI	`opencode`
Continue session	`opencode -c` or `opencode --continue`
Run non-interactive	`opencode run "message"`
Start headless server	`opencode serve`
Web interface	`opencode web`
Switch agent	`Tab` key
File search	`@` then type filename
Undo changes	`/undo`
Redo changes	`/redo`
Share conversation	`/share`
Initialize project	`/init`
Configure API keys	`/connect`

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

Agents

Agent

OpenCode has two primary agents, switchable with

Tab

OpenCode有两个主要Agent，可通过

Tab

键切换：

Build Agent (Default)

构建Agent（默认）

Full access to all tools
Can edit files, run commands, make changes
Use for active development work

拥有所有工具的完整访问权限
可编辑文件、运行命令、进行修改
适用于活跃的开发工作

Plan Agent

规划Agent

Read-only mode for analysis and exploration
File edits and bash commands require approval (
```
ask
```
mode)
Use for reviewing implementation strategy before changes

用于分析和探索的只读模式
文件编辑和bash命令需要批准（
```
ask
```
模式）
适用于在进行更改前审查实现策略

Subagents

子Agent

Invoke subagents with

mention:

@general - Complex research and multi-step tasks with full tool access
@explore - Fast read-only codebase searches and code questions

通过

提及调用子Agent：

@general - 拥有完整工具访问权限，用于复杂研究和多步骤任务
@explore - 快速只读代码库搜索和代码相关问题解答

Keyboard Shortcuts

键盘快捷键

Key	Action
`Tab`	Switch between Build and Plan agents
`@`	Fuzzy file search
`Ctrl+C`	Cancel current operation

按键	操作
`Tab`	在构建Agent和规划Agent之间切换
`@`	模糊文件搜索
`Ctrl+C`	取消当前操作

Slash Commands

斜杠命令

Command	Description
`/connect`	Configure LLM provider API keys
`/init`	Initialize project and create `AGENTS.md`
`/undo`	Revert recent changes (stackable)
`/redo`	Restore undone changes
`/share`	Create shareable conversation link

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

CLI Commands

CLI命令

Interactive Mode

交互模式

bash

undefined

bash

undefined

Start TUI in current directory

在当前目录启动TUI

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

使用特定Agent启动

opencode --agent build opencode --agent plan

undefined

opencode --agent build opencode --agent plan

undefined

Non-Interactive Mode

非交互模式

bash

undefined

bash

undefined

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"

undefined

opencode run --command "npm test"

undefined

Server Mode

服务器模式

bash

undefined

bash

undefined

Start headless API server

启动无头API服务器

opencode serve

With custom port

使用自定义端口

opencode serve --port 3000

With mDNS discovery

启用mDNS发现

opencode serve --mdns

Web interface

网页界面

opencode web

undefined

opencode web

undefined

Management Commands

管理命令

bash

undefined

bash

undefined

Authentication

认证

opencode auth login opencode auth list opencode auth logout

Models

模型

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

opencode models # 列出可用模型 opencode models --refresh # 刷新模型缓存

Agents

Agent

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

opencode agent create # 创建自定义Agent opencode agent list # 列出Agent

MCP servers

MCP服务器

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

opencode session list opencode session list -n 10 # 最近10个会话

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>

undefined

opencode upgrade opencode upgrade <version>

undefined

Built-in Tools

内置工具

OpenCode provides these tools to agents:

Tool	Description
read	Read file contents with optional line ranges
write	Create new files or overwrite existing
edit	Modify files using exact string replacements
patch	Apply patch files
grep	Search file contents with regex
glob	Find files by pattern ( `*/.js` )
list	List files and directories
bash	Execute shell commands
lsp	Language Server Protocol integration (experimental)
todowrite	Create/update task lists
todoread	Read current todo state
skill	Load skill files into conversation
webfetch	Fetch and read web pages
question	Ask user clarifying questions

OpenCode为Agent提供以下工具：

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

Skills

Skill

File Locations

文件位置

Skills are discovered from (in order):

```
.opencode/skills/<name>/SKILL.md
```
(project)

~/.config/opencode/skills/<name>/SKILL.md

(global)

```
.claude/skills/<name>/SKILL.md
```
(Claude-compatible project)
```
~/.claude/skills/<name>/SKILL.md
```
(Claude-compatible global)

Skill的发现顺序如下：

```
.opencode/skills/<name>/SKILL.md
```
（项目级）

~/.config/opencode/skills/<name>/SKILL.md

（全局级）

```
.claude/skills/<name>/SKILL.md
```
（兼容Claude的项目级）
```
~/.claude/skills/<name>/SKILL.md
```
（兼容Claude的全局级）

Skill Format

Skill格式

markdown

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

markdown

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

Skill Content

Instructions and documentation here...

undefined

Instructions and documentation here...

undefined

Name Rules

命名规则

Lowercase alphanumeric with single hyphens
Cannot start/end with hyphens
No consecutive hyphens (
```
--
```
)
Must match directory name

小写字母数字，使用单个连字符分隔
不能以连字符开头或结尾
不能有连续连字符（
```
--
```
）
必须与目录名称匹配

Configuration

配置

Config Locations

配置文件位置

Project:
```
.opencode/
```
or
```
opencode.json
```
Global:
```
~/.config/opencode/
```

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

Environment Variables

环境变量

Variable	Description
`OPENCODE_CONFIG`	Custom config path
`OPENCODE_PERMISSION`	Permission mode
`OPENCODE_SERVER_PASSWORD`	Server auth password
`OPENCODE_DISABLE_AUTOUPDATE`	Disable auto-updates
`OPENCODE_EXPERIMENTAL`	Enable experimental features
`OPENCODE_ENABLE_EXA`	Enable Exa search

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

Custom Agents

自定义Agent

Create agents via

opencode agent create

or define in:

```
opencode.json
```
```
~/.config/opencode/agents/
```
```
.opencode/agents/
```

Agent config options: description, temperature, model, tool permissions, system prompts.

可通过

opencode agent create

创建Agent，或在以下位置定义：

```
opencode.json
```
```
~/.config/opencode/agents/
```
```
.opencode/agents/
```

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

Best Practices

最佳实践

Use Plan Mode First

先使用规划模式

Switch to Plan agent (

Tab

) to review implementation strategy before making changes.

切换到规划Agent（

Tab

键），在进行更改前审查实现策略。

File References

文件引用

Use

@filename

to fuzzy search and reference files in prompts.

在提示中使用

@filename

进行模糊搜索和引用文件。

Undo Stack

撤销栈

Use

/undo

liberally - changes are stackable and reversible with

/redo

灵活使用

/undo

命令 - 更改可堆叠，且可通过

/redo

恢复。

Session Management

会话管理

Use

--continue

-c

to resume previous sessions and maintain context.

使用

--continue

或

-c

恢复之前的会话，保持上下文。

References

参考资料

For detailed documentation, see:

```
references/cli.md
```
- Complete CLI reference
```
references/tools.md
```
- Tool details and permissions
```
references/agents.md
```
- Agent configuration guide

如需详细文档，请查看：

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