代理

OpenCode 有两个主要代理，可使用 Tab 键切换：

构建代理（默认）

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

计划代理

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

子代理

使用 @ 提及来调用子代理：

• @general - 具有完全工具访问权限的复杂研究和多步骤任务
• @explore - 快速的只读代码库搜索和代码问题解答

键盘快捷键

斜杠命令

CLI 命令

交互模式

# 在当前目录启动 TUI
opencode

# 在特定项目中启动
opencode /path/to/project

# 继续之前的会话
opencode --continue
opencode -c

# 使用特定会话
opencode --session <id>
opencode -s <id>

# 使用特定模型启动
opencode --model <model>
opencode -m <model>

# 使用特定代理启动
opencode --agent build
opencode --agent plan

非交互模式

# 运行单次提示
opencode run "修复 auth.py 中的错误"

# 附带文件运行
opencode run "审查这个" --file README.md
opencode run "审查这个" -f README.md

# 运行并分享结果
opencode run "解释这段代码" --share

# 运行特定命令
opencode run --command "npm test"

服务器模式

# 启动无头 API 服务器
opencode serve

# 使用自定义端口
opencode serve --port 3000

# 使用 mDNS 发现
opencode serve --mdns

# Web 界面
opencode web

管理命令

# 认证
opencode auth login
opencode auth list
opencode auth logout

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

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

# MCP 服务器
opencode mcp add <server>
opencode mcp list
opencode mcp auth
opencode mcp debug

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

# 统计
opencode stats
opencode stats --days 7
opencode stats --tools
opencode stats --models

# 导出/导入
opencode export <sessionID>
opencode import <file>

# 升级
opencode upgrade
opencode upgrade <version>

内置工具

OpenCode 为代理提供以下工具：

技能

文件位置

技能从以下位置发现（按顺序）：

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: 描述此技能的作用以及何时使用它。
---

# 技能内容

说明和文档写在这里...

命名规则

• 小写字母数字，可包含单个连字符
• 不能以连字符开头或结尾
• 不能有连续连字符（--）
• 必须与目录名匹配

配置

配置位置

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

环境变量

自定义代理

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

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

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

最佳实践

先使用计划模式

在更改之前，切换到计划代理（Tab）以审查实施策略。

文件引用

在提示中使用 @filename 进行模糊搜索和引用文件。

撤销堆栈

自由使用 /undo - 更改是可堆叠的，并且可以使用 /redo 恢复。

会话管理

使用 --continue 或 -c 来恢复之前的会话并保持上下文。

参考

详细文档请参阅：

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

每周安装数

274

代码仓库

s-hiraoku/synapse-a2a

首次出现

2026年1月24日

安全审计

Gen Agent Trust HubPassSocketPassSnykWarn

安装于

opencode264

gemini-cli242

codex238

github-copilot234

kimi-cli222

amp222

Agents

OpenCode has two primary agents, switchable with Tab:

Build Agent (Default)

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

Plan Agent

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

Subagents

Invoke subagents with @ mention:

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

Keyboard Shortcuts

Slash Commands

CLI Commands

Interactive Mode

# 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

Non-Interactive Mode

# 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"

Server Mode

# Start headless API server
opencode serve

# With custom port
opencode serve --port 3000

# With mDNS discovery
opencode serve --mdns

# Web interface
opencode web

Management Commands

# 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>

Built-in Tools

OpenCode provides these tools to agents:

Skills

File Locations

Skills are discovered from (in order):

1. .agents/skills/<name>/SKILL.md (project, shared with Codex)
2. .claude/skills/<name>/SKILL.md (Claude-compatible project)
3. ~/.config/opencode/skills/<name>/SKILL.md (global)
4. ~/.claude/skills/<name>/SKILL.md (Claude-compatible global)

Skill Format

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

# Skill Content

Instructions and documentation here...

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/

Environment Variables

Custom Agents

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.

Best Practices

Use Plan Mode First

Switch to Plan agent (Tab) to review implementation strategy before making changes.

File References

Use @filename to fuzzy search and reference files in prompts.

Undo Stack

Use /undo liberally - changes are stackable and reversible with /redo.

Session Management

Use --continue or -c to resume previous sessions and maintain context.

References

For detailed documentation, see:

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

Weekly Installs

274

Repository

s-hiraoku/synapse-a2a

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn

Installed on

opencode264

gemini-cli242

codex238

github-copilot234

kimi-cli222

amp222