OpenCode 操作手册前情提要 - 【Agent】openclaw + opencode 打造助手安装篇 0. 环

前情提要 - 【Agent】openclaw + opencode 打造助手安装篇

⚡ OpenCode 速查表

hk4114.github.io_my-reports_reports_OpenCode%20%E9%80%9F%E6%9F%A5%E8%A1%A8.html.png

0. 环境配置

nodejs
opencode opencode --version 查看是否安装成功
推荐git

1. 快速入门

1.1 启动

# 启动 TUI
opencode

# 指定项目目录
opencode /path/to/project

# 继续上一个会话
opencode --continue

# 查看版本
opencode --version

1.2 快捷键

快捷键	功能
`Tab`	切换主代理（Build/Plan）
`@`	引用文件
`!`	执行 bash 命令
`ctrl+x`	斜杠命令前缀

1.3 斜杠命令

命令	功能	快捷键
`/connect`	添加提供商	-
`/compact`	压缩会话	`ctrl+x c`
`/details`	切换工具详情	`ctrl+x d`
`/editor`	打开外部编辑器	`ctrl+x e`
`/exit`	退出	`ctrl+x q`
`/export`	导出对话	`ctrl+x x`
`/help`	显示帮助	`ctrl+x h`
`/init`	创建 AGENTS.md	`ctrl+x i`
`/models`	列出模型	`ctrl+x m`
`/new`	新会话	`ctrl+x n`
`/redo`	重做修改	`ctrl+x r`
`/sessions`	会话列表	`ctrl+x l`
`/themes`	列出主题	`ctrl+x t`
`/undo`	撤销修改	`ctrl+x u`

1.4 CLI 命令

# 非交互模式运行
opencode run "Explain async/await in JavaScript"

# 列出模型
opencode models

# 管理代理
opencode agent list
opencode agent create

# 管理会话
opencode session list
opencode export [sessionID]
opencode import session.json

# 使用特定模型/代理/会话
opencode --model provider/model
opencode --agent <agent-name>
opencode --session <session-id>

# 其他命令
opencode stats        # 统计信息
opencode serve        # 启动服务器
opencode web          # 启动 Web 服务
opencode upgrade      # 升级
opencode uninstall    # 卸载
opencode --print-logs # 打印日志

2. 工作流与技巧

2.1 标准开发流程

添加新功能

按 Tab 切换到计划模式（Plan）
描述需求，获取实现计划
迭代完善计划
按 Tab 切回构建模式（Build）
执行计划

代码审查流程

使用 Plan 代理分析代码
使用 @general 或 @explore 深入研究
使用 /undo 撤销不满意的修改

2.2 撤销与重做

/undo   # 撤销最后一条消息及所有修改
/redo   # 重做之前撤销的内容

注意：项目需要是 Git 仓库才能使用撤销功能。

2.3 最佳实践

初始化项目：始终在项目中运行 /init 创建 AGENTS.md
使用计划模式：复杂任务先规划再执行
提供上下文：使用 @ 引用相关文件
迭代反馈：对计划不满意就提出修改意见
版本控制：确保项目是 Git 仓库以使用撤销功能
配置权限：根据团队需求设置合适的权限
使用技能：将常用工作流封装为技能

3. 规则系统 (AGENTS.md)

3.1 什么是规则

规则（Rules）通过 AGENTS.md 文件为 OpenCode 提供自定义指令，类似于 Cursor 的规则功能。这些指令会被纳入 LLM 上下文，针对特定项目自定义其行为。

3.2 初始化规则文件

# 在 TUI 中运行
/init

提示：应将 AGENTS.md 提交到 Git，与团队共享。

3.3 规则文件位置

级别	路径	说明
项目级	`AGENTS.md`	项目特定规则
全局级	`~/.config/opencode/AGENTS.md`	个人规则（不共享）
Claude兼容	`CLAUDE.md` / `~/.claude/CLAUDE.md`	向后兼容

3.4 引用外部文件

在 opencode.json 中指定多个指令文件：

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

支持远程 URL：

{
  "instructions": [
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

4. 代理系统

4.1 代理类型

主代理（Primary）

直接交互的主要助手：

Build（默认）- 启用所有工具的开发代理
Plan - 受限代理，只分析和规划，不做修改

子代理（Subagent）

主代理调用的专业助手：

General - 通用研究代理
Explore - 只读代码库探索代理

4.2 切换代理

按 Tab 键在主代理间切换
使用 @ 提及调用子代理：

@general help me search for this function

4.3 创建自定义代理

方法一：使用 CLI

opencode agent create

方法二：JSON 配置

{
  "agent": {
    "code-reviewer": {
      "mode": "subagent",
      "description": "Reviews code for best practices",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security and performance.",
      "tools": {
        "write": false,
        "edit": false
      },
      "permission": {
        "edit": "deny"
      }
    }
  }
}

方法三：Markdown 文件

创建 ~/.config/opencode/agents/review.md：

---
description: Reviews code for quality
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
  write: false
  edit: false
---

You are in code review mode. Focus on:

- Code quality
- Potential bugs
- Security considerations

4.4 代理配置选项

选项	描述
`description`	代理功能描述（必填）
`mode`	`primary`、`subagent` 或 `all`
`model`	使用的模型
`prompt`	系统提示词或提示词文件路径
`temperature`	响应随机性（0.0-1.0）
`tools`	可用工具配置
`permission`	权限配置
`steps`	最大迭代步数
`hidden`	是否在补全菜单中隐藏
`color`	UI 颜色（hex 或主题色）

5. MCP 服务器

5.1 什么是 MCP

MCP（Model Context Protocol）允许你添加外部工具和服务，如数据库访问、API 集成等。

5.2 本地 MCP 服务器

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV": "value"
      }
    }
  }
}

5.3 远程 MCP 服务器

{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

5.4 常用 MCP 服务器示例

Sentry

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

认证：opencode mcp auth sentry

Context7（文档搜索）

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Grep by Vercel（GitHub 代码搜索）

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

5.5 MCP 管理命令

# 列出 MCP 服务器
opencode mcp list

# 添加 MCP 服务器
opencode mcp add

# 认证
opencode mcp auth <name>

# 登出
opencode mcp logout <name>

# 调试
opencode mcp debug <name>

6. 推荐插件

6.1 opencode-gemini-auth

链接: github.com/jenslys/ope…
功能: 使用现有的 Gemini 套餐替代 API 计费

6.2 opencode-antigravity-auth

链接: github.com/NoeFabris/o…
功能: 使用 Antigravity 的免费模型替代 API 计费

6.2 oh-my-opencode

链接: github.com/code-yeongy…
功能: 后台代理、预构建的 LSP/AST/MCP 工具、精选代理，兼容 Claude Code

更新 Oh My OpenCode 插件

要强制 OpenCode 检查并更新 oh-my-opencode 插件，你需要修改 oh-my-opencode 自身的配置文件。

找到或创建 ~/.config/opencode/oh-my-opencode.json 配置文件。全局位置: ~/.config/opencode/oh-my-opencode.json；项目位置: 项目根目录下的 .opencode/oh-my-opencode.json。
添加 auto_update 配置在配置文件中添加 "auto_update": true：

{
  //配置文件第一行
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "auto_update": true, // <- 新增这条
  //原有配置👇
  "agents": {
    // ...
  }
}

重启 OpenCode 配置保存后，重启 OpenCode。在启动过程中，插件会自动检测并下载最新版本。注意，这次启动速度会慢，看到白屏或者黑屏的话，耐心等待，不要强行中断，取决于你的网速(特别是连外网的速度)

保留原生Agent

在 ~/.config/opencode/oh-my-opencode.json 文件的第一层级中添加以下配置：

{
  "sisyphus_agent": {
    "default_builder_enabled": true,
    "replace_plan": false
  }
}

修改完成后重启 OpenCode。使用 /agents 命令检查，你应该能看到 plan 和 opencode-builder 两个 Agent 已恢复。节省 Token：原生 Agent 通常更轻量，适合处理简单的任务。快速执行：对于不需要复杂推理的任务，原生 Agent 响应更快。灵活切换：保留原生 Agent 后，你可以根据任务的复杂度在 Sisyphus Agent 和原生 Agent 之间灵活切换。

6.3 opencode-skillful

链接: github.com/zenobi-us/o…
功能: 技能管理工具

安装后，你可以使用以下三个核心工具：

skill_find "关键词" - 搜索技能
skill_use "skill_name" - 加载技能到对话中
skill_resource skill_name="name" relative_path="path" - 读取技能资源文件

配置技能路径（可选）：创建 ~/.config/opencode-skillful/config.json：

{
  "debug": false,
  "basePaths": ["~/.config/opencode/skills", ".opencode/skills"],
  "promptRenderer": "xml"
}

7. 故障排除

7.1 OpenCode 无法启动

检查日志中的错误消息
使用 --print-logs 运行查看终端输出
运行 opencode upgrade 更新到最新版本

7.2 身份验证问题

在 TUI 中使用 /connect 重新认证
检查 API 密钥是否有效
确保网络允许连接到提供商 API

7.3 ProviderInitError

验证提供商配置
清除配置：rm -rf ~/.local/share/opencode
重新运行 /connect 认证

7.4 AI_APICallError

清除提供商包缓存：

rm -rf ~/.cache/opencode

7.5 文件位置

日志文件位置

macOS/Linux: ~/.local/share/opencode/log/
Windows: %USERPROFILE%\.local\share\opencode\log

存储位置

macOS/Linux: ~/.local/share/opencode/
Windows: %USERPROFILE%\.local\share\opencode

包含：

auth.json - API 密钥、OAuth Token
log/ - 应用日志
project/ - 项目会话数据

7.6 常见故障速查表

问题	解决方案
模型不响应	检查 API 密钥和网络连接
工具被禁用	检查 `permission` 配置
MCP 不工作	运行 `opencode mcp debug <name>`
无法撤销	确保项目是 Git 仓库
性能问题	使用 `/compact` 压缩会话
上下文溢出	增加 `compaction.reserved` 值