AI 开发环境最佳实践：opencode + OhMyOpenCode + tmux

一套终端原生的 AI 编码工作流：让 AI 代理"跑得起来、指挥得动、还挂不断"。

组件	角色	一句话用途	核心效果
opencode	AI 引擎	终端里的 AI 编程代理，读写代码、执行命令	让 AI 真正"动手"，而不是只聊天
OhMyOpenCode	编排层	挂在 opencode 上的多代理编排插件	把"一个 AI"升级成"一支分工明确的 AI 团队"
tmux	会话层	终端复用器，会话脱离终端后继续运行	SSH 断了、关终端了、换电脑了，任务照跑

下面逐一说明它们是什么、为什么值得用，然后给出完整的安装与配置步骤。

第 1 章：opencode —— 终端原生的 AI 编程代理

1.1 它是什么

opencode 是一个开源、终端原生的 AI 编程代理（AI coding agent）。它提供一个 TUI 界面，让模型能够直接读取和修改你的代码、执行 shell 命令，而不仅仅是生成一段文本让你自己粘贴。

它的关键能力：

终端 TUI 交互：在终端里完成从对话到改文件的全过程
多模型 / 多 Provider：支持 Anthropic、OpenAI、Gemini 以及任意 OpenAI 兼容接口，也支持本地模型
内置 Agent：build（写代码）、plan（只规划不改文件），以及 explore、general 等子代理
MCP 支持：接入本地或远程 MCP 服务器，扩展工具能力
slash commands：/init、/models、/share 等内置命令
Git 快照：每一步自动打快照，可用 /undo、/redo 回退

opencode 除了终端 TUI，还提供**桌面版（Desktop）**客户端：图形化界面，适合不习惯纯终端、或想在独立窗口里管理多个会话的用户。桌面版与终端版共享同一套配置（ ~/.config/opencode/opencode.json ）与凭据。

1.2 安装

有三种主流方式，任选其一：

bash

# 方式一：官方安装脚本（最简单）
curl -fsSL https://opencode.ai/install | bash

# 方式二：npm
npm install -g opencode-ai

# 方式三：Homebrew（macOS）
brew install opencode

# 方式四：桌面版（GUI）
# 从 https://opencode.ai 下载对应系统的桌面安装包（macOS / Windows / Linux）

说明：npm 包名是 opencode-ai（不是 opencode ）。安装脚本默认安装到 ~/.opencode/bin ，如需指定目录可用 OPENCODE_INSTALL_DIR=/usr/local/bin 环境变量覆盖。官方文档见 opencode.ai。

安装后验证：

bash

opencode --version

1.3 启动与首次配置

进入项目目录后直接运行：

bash

cd /path/to/your-project
opencode

首次使用按以下顺序操作：

输入 /connect，选择一个模型 Provider（如 Anthropic），完成浏览器授权或填入 API Key
在项目里运行 /init —— 它会分析项目结构，在根目录生成或更新 AGENTS.md（告诉 AI 这个项目的约定）

text

/connect    # 配置模型 Provider 和 API Key
/init       # 初始化项目上下文（生成 AGENTS.md）

1.4 配置文件：位置、优先级与资源目录

opencode 的配置是分层合并的——不是后加载的替换先加载的，而是逐字段合并，后加载的源只覆盖冲突字段。配置同时支持 JSON 和 JSONC（带注释），schema 是 https://opencode.ai/config.json 。

配置文件的位置与优先级

opencode 会从多个位置读取配置，优先级从低到高如下（越高越晚加载、越能覆盖前面的值）：

优先级	位置	说明
1（最低）	Remote `.well-known/opencode`	组织/团队统一下发的默认配置
2	全局 `~/.config/opencode/opencode.json`	个人全局默认
3	环境变量 `OPENCODE_CONFIG` 指向的文件	自定义路径的配置文件
4	项目根 `opencode.json` / `opencode.jsonc`	标准配置里优先级最高；启动时 opencode 会从当前目录向上找到最近的 git 目录作为项目根
5	`.opencode/` 目录	项目级的 agents/commands/plugins 等资源（见下文）

日常你只需要关心两个：**全局 ~/.config/opencode/opencode.json （你的通用偏好）和项目根 opencode.jsonc **（这个仓库特有的覆盖）。项目配置的冲突字段赢过全局。

TUI（界面）相关的主题、键位有独立的配置文件，与主配置分开：

text

~/.config/opencode/tui.json     # 全局界面配置
tui.json                        # 项目级界面配置
# 也可用 OPENCODE_TUI_CONFIG 指定自定义路径
# schema: https://opencode.ai/tui.json

资源目录：agents / commands / plugins / skills / …

除了单个配置文件，opencode 还会扫描一组复数命名的子目录来加载资源。这些目录可以放在两处：**项目级 .opencode/ ** 或 **全局 ~/.config/opencode/ **（单数形如 agent/ 为向后兼容也认，但推荐复数）：

text

.opencode/                        # 项目级（或 ~/.config/opencode/ 全局）
├── agents/      # 自定义代理（.md 文件，文件名即代理名）
├── commands/    # 自定义 slash 命令（.md 文件）
├── plugins/     # 本地插件（.ts 文件）
├── skills/      # Agent Skills，每个技能一个文件夹 + SKILL.md
├── tools/       # 自定义工具
└── themes/      # 自定义主题

还可以用环境变量 OPENCODE_CONFIG_DIR 指向一个自定义目录，它会在全局 + .opencode 之后再扫描 agents/commands/plugins，因此能覆盖前面的同名资源。

这些资源大多既能在 opencode.json 里用 JSON 字段配，也能用对应目录里的 Markdown 文件配，两者等价，按需选一种。下面逐个展开。

Agents（代理）

代理定义在配置文件的 agent 对象里，或 agents/*.md（带 YAML frontmatter，文件名即代理名）：

jsonc

{
  "agent": {
    "reviewer": {
      "description": "只读审查，不改文件",   // 必填
      "mode": "subagent",                    // primary / subagent / all（默认 all）
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "Review for bugs, security issues, and maintainability.",
      "permission": { "edit": "deny", "bash": "deny" }
    }
  },
  "default_agent": "build"   // 默认主代理，必须是 primary
}

等价的 Markdown 写法 .opencode/agents/reviewer.md：

markdown

---
description: 只读审查，不改文件
mode: subagent
permission:
  edit: deny
  bash: deny
---

Review for bugs, security issues, and maintainability.

内置代理：primary 有 build（默认，开放全部工具）和 plan（受限，edit/bash 默认 ask）；子代理有 general / explore / scout。用 Tab 键在主代理间切换；子代理通过 @代理名 或自动委派调用。opencode agent create 可交互式生成一个代理。

Commands（自定义命令）

自定义 slash 命令定义在 command 对象里，或 commands/*.md，之后用 /命令名 调用：

jsonc

{
  "command": {
    "review": {
      "template": "Review this code for bugs: $ARGUMENTS",  // $ARGUMENTS 接收命令后带的参数
      "description": "代码审查",
      "agent": "reviewer",
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

等价的 Markdown 写法 .opencode/commands/review.md：

markdown

---
description: 代码审查
agent: reviewer
---

Review this code for bugs: $ARGUMENTS

Plugins（插件）

插件有两种装法：把本地 TypeScript 文件放进 plugins/ 目录，或在配置文件的 plugin 数组里引用 npm 包（具体见 1.7）。插件用来扩展自定义工具、hooks 和外部集成。

text

.opencode/plugins/my-plugin.ts        # 项目级本地插件
~/.config/opencode/plugins/my-plugin.ts   # 全局本地插件

Skills（Agent Skills）

每个技能单独一个文件夹，里面放一个 SKILL.md：

text

.opencode/skills/pdf-extract/SKILL.md        # 项目级
~/.config/opencode/skills/pdf-extract/SKILL.md   # 全局
# 还兼容 Claude 生态的位置：.claude/skills/、~/.claude/skills/、.agents/skills/、~/.agents/skills/

SKILL.md 的 frontmatter 至少要有 name（小写连字符，必须和文件夹名一致）和 description；license/compatibility/metadata 可选：

markdown

---
name: pdf-extract
description: 从 PDF 中提取文本与表格
---

在这里写技能的具体指令……

代理通过原生 skill 工具按需加载它们（出现在 <available_skills> 里）。权限可用 permission.skill 按模式（allow/deny/ask，支持通配符）控制，也能按代理覆盖；"tools": { "skill": false } 可整体禁用。

一个综合的最小配置

把模型、自定义代理、权限、MCP 放在一起的项目级 opencode.jsonc ：

jsonc

{
  "$schema": "https://opencode.ai/config.json",

  // 默认模型，格式为 provider/model
  "model": "anthropic/claude-sonnet-4-5",

  // 自定义一个"只读审查"子代理
  "agent": {
    "reviewer": {
      "description": "Reviews code without modifying files",
      "mode": "subagent",
      "prompt": "Review for bugs, security issues, and maintainability.",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  },

  // 全局权限：改文件/执行命令前询问
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },

  // 接入一个远程 MCP 服务器
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

接 OpenAI 兼容接口的示例——以 DeepSeek 为例（它提供 OpenAI 兼容的 API，自建网关、Kimi 等同理）：

jsonc

{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DeepSeek",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      },
      "models": {
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  },

  "model": "deepseek/deepseek-v4-pro"
}

1.5 API Key 与认证

推荐走 TUI 里的 /connect，凭据会保存到 ~/.local/share/opencode/auth.json
也支持环境变量：

bash

export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."

查看已保存的凭据：

bash

opencode auth list

1.6 常用 slash commands 与键位

text

/init      初始化 / 更新 AGENTS.md
/connect   配置模型 Provider / API Key
/models    查看和选择模型
/share     分享当前会话
/sessions  列出并切换历史会话
/undo      撤销上一轮操作及文件修改
/redo      重做已撤销的操作
/compact   压缩当前会话上下文
/themes    切换主题

1.7 常用插件（Plugins）

opencode 通过 opencode.json 里的 plugin 数组加载插件。以下是几个值得装的常用插件：

jsonc

{
  "plugin": [
    "@tarquinen/opencode-dcp@latest",
    "opencode-gemini-auth@latest",
    "opencode-antigravity-auth@latest",
    "[email protected]"
  ]
}

插件	用途
`@tarquinen/opencode-dcp`	动态上下文裁剪（Dynamic Context Pruning）：自动删除过期的工具输出、去重、清理错误输入，显著降低 token 消耗。提供 `/dcp` 、 `/dcp stats` 、 `/dcp context` 、 `/dcp compress` 等命令
`opencode-gemini-auth`	用你已有的 Gemini 订阅做 OAuth 认证，而不是走 API 计费
`opencode-antigravity-auth`	用 Google Antigravity（IDE）的免费额度做 OAuth 认证，可访问 Gemini 3 与 Claude Opus/Sonnet 等模型，并支持 Google Search grounding
`oh-my-openagent`	多代理编排插件（详见第 3 章），此处固定版本 `v4.19.4`

⚠️ 认证插件冲突： opencode-gemini-auth 与 opencode-antigravity-auth 都会为 google provider 注册 OAuth，同时安装时可能只显示一个认证入口，建议二选一（ antigravity-auth 已整合 Gemini CLI 配额，通常更省心）。关于 Gemini 的接入细节与已知问题，见第 2 章。

第 2 章：在 opencode 里用好 Gemini（Antigravity）

前端/视觉类代码（布局、样式、动画、组件还原）对多模态理解和长上下文要求很高——经常要读设计稿截图、对照几十个文件。这正是 Gemini 系列（尤其是 Gemini 3 Pro）的强项：原生多模态、超长上下文、对视觉细节敏感。而后端/纯逻辑任务用 Claude、Kimi 等往往更稳。所以实际使用中，把前端任务单独路由到 Gemini 是性价比很高的做法。

2.1 一个要先知道的坑：opencode 直接用 Gemini 容易异常

先说结论：在 opencode 里直接配 Gemini（API Key 或 opencode-gemini-auth）经常会异常。常见表现是：

工具调用（function calling）格式不兼容：Gemini 对 tool_use / tool_result 的协议和 Anthropic、OpenAI 不完全一致，多轮工具调用后容易报 400、参数解析失败或直接卡住；
长上下文下稳定性差：会话一长，容易触发截断、空响应或无限重试；
流式中断：偶发地流式输出到一半断开，需要重发。

也就是说，Gemini 模型本身很强，但它和 opencode 当前的工具调用链路磨合得还不够好，当作主力代理模型直接用，体验往往不稳定。

2.2 解法：走 Antigravity 的 OAuth 通道

Antigravity 是 Google 官方推出的免费 AI IDE，内置 Gemini 3 与 Claude Opus/Sonnet 等模型额度。opencode-antigravity-auth 这个插件的作用，是复用 Antigravity 的免费 OAuth 额度，让你在 opencode 里不花 API 钱就能调 Gemini 3——而且走的是 Antigravity 封装好的兼容通道，比裸连 Gemini API 稳定得多，正好绕开 2.1 里那些异常。

配置分两步：

1. 认证：确保 plugin 数组里有 opencode-antigravity-auth@latest，然后在 TUI 里 /connect，选择 Antigravity / Google 走 OAuth 授权，即可把 Antigravity 的模型接入 google provider。

2. 把前端类别路由到 Gemini：配合第 3 章 OmO 的类别路由，把 visual-engineering（前端/视觉）类别指定到 Antigravity 提供的 Gemini 模型，让前端任务自动落到最擅长的模型上：

jsonc

// .opencode/oh-my-openagent.jsonc
{
  "categories": {
    "visual-engineering": {
      "model": "google/gemini-3-pro-preview"   // 经 Antigravity OAuth 调用的 Gemini
    }
  }
}

这样其余类别继续用你惯用的模型，只有前端/视觉任务被路由到 Gemini——既吃到它的多模态红利，又避开直连的不稳定，还不增加 API 成本。

第 3 章：OhMyOpenCode —— 把"一个 AI"升级成"一支 AI 团队"

3.1 它是什么

OhMyOpenCode（项目现名 Oh My OpenAgent，简称 OmO）不是另一个 AI 代理，而是挂在 opencode 之上的编排插件。它把 opencode 的单一编程代理，扩展成一个多模型、多专长的代理协作系统。

一句话概括它的价值：

主代理负责规划任务、并行委派子代理、再整合结果 —— 你不再手动安排"先做 A 再做 B"，而是把整件事交给编排层。

核心架构：

Sisyphus：主编排代理，规划 + 分派 + 整合
Oracle：架构设计与疑难调试的咨询代理
Librarian / Explore：文档检索、远程代码查找、代码库探索
按任务类别路由模型：visual-engineering（前端/视觉）、ultrabrain（硬逻辑）、deep（自主深度研究）、quick（琐碎改动）、writing（文档）等，每个类别用最合适的模型处理

它还带来这些能力：

后台并行子代理：多个探索/研究任务同时跑
Team Mode：真正的多代理团队（lead + 多个并行成员），可用 tmux 实时观察
Skills / MCP / LSP / AST-Grep 等工具链
持续执行工作流：如 ultrawork / ulw 等触发词
/init-deep：生成分层 AGENTS.md 知识库

⚠️ 命名提示：该项目正处于 oh-my-opencode → oh-my-openagent 的改名阶段。旧资料里的 oh-my-opencode 、 ~/.config/opencode/oh-my-opencode.jsonc ，和新文档里的 oh-my-openagent 、 ~/.config/opencode/oh-my-openagent.jsonc 会同时出现 —— 这是同一项目的改名迁移，不是两个独立项目。以维护者仓库 code-yeongyu/oh-my-openagent 为准。

3.2 安装

OmO 是一个 opencode 插件，在 opencode.json 的 plugin 数组里声明即可：

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["[email protected]"]
}

也可以用命令行安装：

bash

opencode plugin install oh-my-openagent

安装后会额外提供一个 omo 命令（等价于 oh-my-opencode / oh-my-openagent ）。

⚠️ 不要手动 git clone 到 ~/.config/opencode 。它是作为 opencode 插件加载的：插件会自动注册进 opencode，并生成 OmO 自己的配置。

涉及的文件：

text

~/.config/opencode/opencode.json                # 注册插件（全局）
~/.config/opencode/oh-my-openagent.jsonc        # OmO 全局配置
.opencode/oh-my-openagent.jsonc                 # 项目级配置

3.3 配置

OmO 自身的配置写在 .opencode/oh-my-openagent.jsonc（项目级）或 ~/.config/opencode/oh-my-openagent.jsonc（全局）。顶层字段控制整体行为，最常用的是这几个：

jsonc

// .opencode/oh-my-openagent.jsonc
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "atlas": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "volcengine-code-plan/kimi-k2.7-code"
    },
    "explore": {
      "fallback_models": [
        {
          "model": "opencode-go/minimax-m3"
        }
      ],
      "model": "volcengine-code-plan/glm-5.2"
    },
    "hephaestus": {
      "description": "",
      "model": "volcengine-code-plan/glm-5.2"
    },
    "librarian": {
      "fallback_models": [
        {
          "model": "opencode-go/minimax-m3"
        }
      ],
      "model": "volcengine-code-plan/kimi-k2.7-code"
    },
    "metis": {
      "model": "volcengine-code-plan/glm-5.2"
    },
    "momus": {
      "model": "volcengine-code-plan/kimi-k3"
    },
    "multimodal-looker": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "volcengine-code-plan/glm-5.2"
    },
    "oracle": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "volcengine-code-plan/kimi-k2.7-code"
    },
    "prometheus": {
      "model": "volcengine-code-plan/kimi-k2.7-code"
    },
    "sisyphus": {
      "description": "强大的 AI 编排器。极度严谨地通过待办事项（To-Do）进行规划，在执行探索前会预先评估搜索复杂度，并基于‘类别+技能’的组合策略性地进行任务委派。针对内部代码使用 explore 工具（支持并行执行），针对外部文档使用 librarian 工具。(Sisyphus - OhMyOpenCode)",
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "volcengine-code-plan/glm-5.2"
    },
    "sisyphus-junior": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "volcengine-code-plan/kimi-k2.7-code"
    }
  },
  "categories": {
    "artistry": {
      "fallback_models": [
        {
          "model": "opencode-go/glm-5.1"
        }
      ],
      "model": "agent-plan/glm-5.2"
    },
    "deep": {
      "fallback_models": [
        {
          "model": "opencode-go/glm-5.1"
        }
      ],
      "model": "agent-plan/glm-5.2"
    },
    "quick": {
      "model": "agent-plan/glm-5.2"
    },
    "ultrabrain": {
      "model": "agent-plan/glm-5.2"
    },
    "unspecified-high": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "agent-plan/glm-5.2"
    },
    "unspecified-low": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "agent-plan/glm-5.2"
    },
    "visual-engineering": {
      "model": "volcengine-code-plan/kimi-k2.7-code"
    },
    "writing": {
      "fallback_models": [
        {
          "model": "deepseek/deepseek-v4-pro"
        }
      ],
      "model": "agent-plan/kimi-k3"
    }
  },
  "git_master": {
    "commit_footer": false,
    "include_co_authored_by": false
  },
  "i18n": {
    "locale": "zh"
  },
  "team_mode": {
    "enabled": true,
    "max_members": 8,
    "max_parallel_members": 4,
    "tmux_visualization": true
  },
  "tmux": {
    "agent_pane_min_width": 40,
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_min_width": 120,
    "main_pane_size": 60
  }
}

default_run_agent：默认编排器，通常填 sisyphus。
agent_order：代理的选择优先级，越靠前越优先。
disabled_* 系列：OmO 默认注入大量 MCP、代理、技能和工具，用不到的在这里裁剪掉，能明显降低上下文噪声。
model_fallback：某个 provider 调用失败时自动回退到备用模型，建议开启。

需要团队协作时，再开启 Team Mode（默认关闭）：

jsonc

{
  "team_mode": {
    "enabled": true,
    "max_parallel_members": 4,
    "tmux_visualization": true
  }
}

更完整的字段说明见本站《oh-my-openagent：OpenCode 的「全家桶」智能体编排插件》一文。

3.4 使用

安装完成后，重新进入 opencode TUI，在代理选择器（agent selector）里就能看到 Sisyphus / Oracle / Librarian / Explore 等代理，切换主代理即可。

日常用触发词驱动编排工作流：

text

ultrawork / ulw    深度执行工作流
search             检索
analyze            分析
hyperplan          多代理对抗式规划

具体可用触发词会随版本变化，以当前安装版本的 TUI 与安装指南为准。

第 4 章：tmux —— 让 AI 任务挂不断、看得到

4.1 它是什么

tmux 是终端复用器（terminal multiplexer）：在一个终端里运行多个窗口（window）和面板（pane），并且会话脱离终端后继续运行，之后随时重新连接。

对 AI 开发，它的价值是实打实的：

SSH 断了 / 关了终端 / 换了电脑，正在跑的 AI 代理、编译、测试任务照常运行
一个窗口拆成多个 pane：左边跑 AI 代理、右边看日志、下面跑测试
detach/reattach，随时随地接着上次的会话继续
多个客户端连进同一会话，适合结对或远程协作

4.2 安装

先把 tmux 本体装上（要求 >= 2.6 ），再用 gpakosz/.tmux（项目名 "Oh my tmux!"）这套开箱即用的配置替换掉默认配置——它自带 Powerline 风格状态栏、Vim 式键位、SSH/Mosh 感知、电池/uptime 显示等一长串贴心默认。

bash

# 1. 先装 tmux 本体
brew install tmux                          # macOS
sudo apt update && sudo apt install tmux   # Ubuntu / Debian

# 2. 一条命令安装 Oh my tmux!（会自动备份旧配置）
curl -fsSL "https://github.com/gpakosz/.tmux/raw/refs/heads/master/install.sh#$(date +%s)" | bash

不喜欢管道脚本的话，手动安装等价：

bash

cd
git clone --single-branch https://github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf
cp .tmux/.tmux.conf.local .

验证：

bash

tmux -V

前提： TERM 需为 xterm-256color （iTerm2 / 大多数现代终端默认即满足），系统里要有 awk 、 perl 、 sed 、 grep 。

4.3 实战：一条命令把 opencode 挂进 tmux 会话

每次手动 tmux new -s xxx 再敲 opencode ，要现想会话名、现挑端口，繁琐。可以把这个流程封装成一个 shell 函数，放进 ~/.zshrc （bash 用户放 ~/.bashrc ），之后进项目目录敲一个 oc 就自动完成「建会话 → 选端口 → 启动 opencode → 退出后回到 shell」整套动作：

bash

# ~/.zshrc
oc() {
    local base_name=$(basename "$PWD")
    local path_hash=$(echo "$PWD" | md5sum | cut -c1-4)
    local session_name="${base_name}-${path_hash}"

    # 找一个可用端口
    local port=4096
    while [ $port -lt 5096 ]; do
        if ! lsof -i :$port >/dev/null 2>&1; then
            break
        fi
        port=$((port + 1))
    done

    export OPENCODE_PORT=$port

    if [ -n "$TMUX" ]; then
        opencode --port $port "$@"
    else
        local oc_cmd="OPENCODE_PORT=$port opencode --port $port $*; exec $SHELL"
        if tmux has-session -t "$session_name" 2>/dev/null; then
            tmux new-window -t "$session_name" -c "$PWD" "$oc_cmd"
            tmux attach-session -t "$session_name"
        else
            tmux new-session -s "$session_name" -c "$PWD" "$oc_cmd"
        fi
    fi
}

用法：

bash

cd /path/to/project
oc                # 自动建/attach 一个以项目目录命名的 tmux 会话，并在其中启动 opencode
source ~/.zshrc   # 首次添加后记得重载一次

这个函数做了四件事：

逻辑	作用
`basename + 路径哈希前 4 位` 生成会话名	同一个目录反复 `oc` 复用同一个会话，不会开出一堆重复会话
`4096~5096` 区间找空闲端口	opencode 是 server/client 架构，多实例必须端口隔离； `OPENCODE_PORT` 一并导出，让子进程知道连哪个端口
已在 tmux 内（ `$TMUX` 非空）则直接跑	避免再嵌套一层会话
`opencode ...; exec $SHELL`	opencode 退出后仍留在 shell，而不是把整个 tmux 会话一起关掉

小贴士：macOS 默认没有 md5sum （可用 md5 -q 替代，或先 brew install coreutils 用 gmd5sum ）。在 macOS 上把 path_hash 那行换成 local path_hash=$(echo "$PWD" | md5 -q | cut -c1-4) 即可。

第 5 章：把它们串起来的日常工作流

三者配合的典型日常是这样：进项目目录敲一条 oc（按 4.3 配好的 shell 函数），自动完成「建会话 → 选端口 → 启动编排后的 opencode」整套动作：

bash

cd /path/to/project
oc
# 进入 opencode 后选择 Sisyphus 主代理，直接下达高层目标：
#   > 用 TDD 给 UserService 加一个 email 校验，跑完测试给我结果

至此形成一条完整的链路：

opencode 负责真正读码、改码、跑命令
OhMyOpenCode 负责把复杂任务拆解、并行委派给最合适的子代理
tmux 负责让整个过程挂不断、看得见、可恢复 —— 你 <prefix> + d 走人，任务继续；回来看 tmux attach 无缝续上

结语

三个工具解决的是三个正交的问题，组合起来恰好覆盖了 AI 开发环境最核心的需求：跑得起来（opencode）、指挥得动（OhMyOpenCode）、挂不断（tmux）。

如果只能记住一句话，那就是：

opencode 是引擎，OhMyOpenCode 是大脑，tmux 是铠甲。

下一步建议：先装 opencode 跑通 /connect + /init ，再叠加 OhMyOpenCode 感受多代理编排，最后用 tmux + tmux-continuum 把整套环境变成 7×24 常驻的工作台。

AI 开发环境最佳实践：opencode + OhMyOpenCode + tmux ​

第 1 章：opencode —— 终端原生的 AI 编程代理 ​

1.1 它是什么 ​

1.2 安装 ​

1.3 启动与首次配置 ​

1.4 配置文件：位置、优先级与资源目录 ​

配置文件的位置与优先级 ​

资源目录：agents / commands / plugins / skills / … ​

Agents（代理） ​

Commands（自定义命令） ​

Plugins（插件） ​

Skills（Agent Skills） ​

一个综合的最小配置 ​

1.5 API Key 与认证 ​

1.6 常用 slash commands 与键位 ​

1.7 常用插件（Plugins） ​

第 2 章：在 opencode 里用好 Gemini（Antigravity） ​

2.1 一个要先知道的坑：opencode 直接用 Gemini 容易异常 ​

2.2 解法：走 Antigravity 的 OAuth 通道 ​

第 3 章：OhMyOpenCode —— 把"一个 AI"升级成"一支 AI 团队" ​

3.1 它是什么 ​

3.2 安装 ​

3.3 配置 ​

3.4 使用 ​

第 4 章：tmux —— 让 AI 任务挂不断、看得到 ​

4.1 它是什么 ​

4.2 安装 ​

4.3 实战：一条命令把 opencode 挂进 tmux 会话 ​

第 5 章：把它们串起来的日常工作流 ​

结语 ​

AI 开发环境最佳实践：opencode + OhMyOpenCode + tmux

第 1 章：opencode —— 终端原生的 AI 编程代理

1.1 它是什么

1.2 安装

1.3 启动与首次配置

1.4 配置文件：位置、优先级与资源目录

配置文件的位置与优先级

资源目录：agents / commands / plugins / skills / …

Agents（代理）

Commands（自定义命令）

Plugins（插件）

Skills（Agent Skills）

一个综合的最小配置

1.5 API Key 与认证

1.6 常用 slash commands 与键位

1.7 常用插件（Plugins）

第 2 章：在 opencode 里用好 Gemini（Antigravity）

2.1 一个要先知道的坑：opencode 直接用 Gemini 容易异常

2.2 解法：走 Antigravity 的 OAuth 通道

第 3 章：OhMyOpenCode —— 把"一个 AI"升级成"一支 AI 团队"

3.1 它是什么

3.2 安装

3.3 配置

3.4 使用

第 4 章：tmux —— 让 AI 任务挂不断、看得到

4.1 它是什么

4.2 安装

4.3 实战：一条命令把 opencode 挂进 tmux 会话

第 5 章：把它们串起来的日常工作流

结语