终端AI编程助手Crush：架构解析、实战配置与高级功能指南-洪萨配资

1. 项目概述：一个为终端而生的AI编码伙伴

如果你和我一样，大部分工作时间都“住”在终端里，那你肯定经历过这种场景：正在用vim或neovim调试一段复杂的Go协程代码，突然卡在一个并发死锁问题上。这时候，你不得不离开心爱的终端，打开浏览器，点开某个AI助手的网页，把代码片段复制过去，等待回复，再把答案复制回终端。这个上下文切换的过程不仅打断了你的心流，还让整个解决问题的体验变得支离破碎。

OpenCode（现在已更名为Crush）就是为了解决这个痛点而生的。它是一个用Go编写的、完全运行在终端里的AI助手。它的核心目标很简单：让你无需离开终端，就能获得强大的AI编码辅助。无论是解释一段晦涩的代码、生成一个复杂的Bash脚本、还是帮你重构一个函数，你都可以直接在终端里完成交互。它不是一个简单的命令行包装器，而是一个功能完整的TUI（终端用户界面）应用，内置了会话管理、文件操作、代码编辑、甚至与语言服务器（LSP）集成的能力。

这个项目最初名为OpenCode，现在由原开发者和Charm团队继续维护，并更名为Crush。但无论是哪个名字，其核心理念没有变：为开发者提供一个高效、专注、不打断工作流的AI编程环境。它支持几乎所有主流的AI模型提供商，从OpenAI、Anthropic Claude到Google Gemini、Groq，甚至包括GitHub Copilot和自托管模型。这意味着你可以根据需求、成本或性能，灵活选择最适合你的“大脑”。

对我个人而言，从Vim切换到Neovim的一个重要原因就是追求“终端内完成一切”的纯粹体验。OpenCode/Crush将这一理念延伸到了AI辅助编程领域，它让我能保持双手不离键盘，眼睛不离开代码，在同一个上下文中快速获得智能帮助。接下来，我将详细拆解它的设计思路、核心功能、以及我在深度使用和配置过程中积累的一系列实战经验与避坑指南。

2. 核心设计思路与架构解析

2.1 为什么选择终端原生（TUI）？

在Web界面和独立桌面应用大行其道的今天，为什么还要做一个终端应用？这背后有几个关键的考量。

首先是极致的上下文保持。开发者的核心工作环境就是终端和编辑器。当你在终端中运行测试、查看日志、操作Git时，问题往往就出现在当前上下文中。一个终端内的AI助手可以直接读取你的当前工作目录、环境变量、甚至正在运行的进程状态（通过工具调用），它所提供的建议天生就与你的工作场景高度相关。相比之下，切换到浏览器意味着你要手动复制粘贴文件路径、代码片段，丢失了大量有价值的上下文信息。

其次是无与伦比的启动速度和响应性。一个Go编译的二进制文件，启动几乎是瞬间的。没有Electron的笨重，没有浏览器标签页的切换延迟。当你遇到问题，敲入opencode，界面即刻呈现，这种“召之即来”的体验对于需要频繁、快速咨询的场景至关重要。

再者是与现有工作流的无缝集成。OpenCode/Crush支持通过管道（pipe）和非交互模式（-p参数）运行。这意味着你可以轻松地将它嵌入到脚本、Makefile或CI/CD流程中。例如，你可以写一个脚本，在每次提交前自动用AI检查代码注释，或者让它在代码审查时自动生成变更摘要。这种可编程性是Web应用难以提供的。

最后是对远程开发的友好支持。很多开发者会通过SSH连接到远程服务器或容器中进行开发。在这种环境下，图形界面往往不可用或性能堪忧。一个纯终端的AI工具就成了唯一可行的选择，它能让你在远程服务器上也能享受本地级别的AI辅助。

2.2 模块化架构：如何支撑复杂功能？

OpenCode的代码结构清晰地反映了其模块化的设计思想。这种设计不仅让代码易于维护和扩展，也让我们能清晰地理解各个部分是如何协同工作的。

核心服务层（internal/app）：这是应用的中枢，负责协调TUI、LLM调用、会话管理、工具执行等所有核心流程。它采用了一种类似事件总线的设计，TUI的交互（如用户发送消息）会触发相应的事件，由服务层分发给对应的处理器（Handler）去执行，比如调用AI模型、执行一个Bash命令、或更新数据库。

配置管理（internal/config）：它采用了一种灵活的配置加载策略，依次从./.opencode.json（项目级）、$XDG_CONFIG_HOME/opencode/.opencode.json（用户级）、$HOME/.opencode.json（用户级备用）读取配置，并支持环境变量覆盖。这种优先级设计非常实用：你可以在项目根目录放一个配置文件，为这个项目指定特定的AI模型或API密钥，而不会影响你的全局设置。

LLM提供商抽象层（internal/llm）：这是项目中最精彩的部分之一。它定义了一个统一的Provider接口，所有具体的AI服务（OpenAI、Anthropic、Gemini等）都实现这个接口。这意味着添加一个新的AI提供商（比如新出的某家API），只需要实现几个标准方法即可，核心的业务逻辑完全不用改动。这种设计也使得“模型”和“提供商”解耦，你可以在配置中指定claude-3.7-sonnet，系统会自动找到对应的Anthropic提供商来调用。

工具执行引擎：AI之所以能“动手”操作你的系统（读文件、执行命令），全靠这套工具系统。每个工具（如bash，view，write）都是一个独立的Go结构体，实现了Tool接口。当AI决定使用某个工具时，它会生成一个结构化的JSON请求，包含工具名和参数。执行引擎会解析这个请求，找到对应的工具实例，执行它，并将结果（成功或错误）格式化成AI能理解的文本，传回对话上下文。这里有一个关键的安全机制：权限确认。对于高风险操作（如执行任意Shell命令、写入文件），TUI会弹出一个对话框，明确询问你是否允许。你可以选择“本次允许”、“本次会话允许”或“拒绝”。这个设计在赋予AI强大能力的同时，也筑起了一道至关重要的安全防线。

TUI框架（internal/tui）：基于Charm团队的Bubble Tea库构建。Bubble Tea是一个遵循Elm架构的TUI框架，其核心是Model（状态）、Update（更新函数）、View（渲染函数）和Msg（消息）。OpenCode的TUI被组织成多个“页面”（Page）或“模式”（Mode），如聊天主页面、会话切换对话框、模型选择对话框、日志页面等。每个页面都有自己的Model和消息处理逻辑。这种组件化的设计使得复杂的TUI界面变得清晰可管理。

2.3 数据持久化：会话与记忆

一个实用的AI助手必须能记住之前的对话。OpenCode使用SQLite作为本地数据库，这是一个非常轻量且正确的选择。所有会话（Session）、消息（Message）、工具调用记录都存储在SQLite文件中。数据库模式设计考虑了扩展性，例如，消息表不仅存储内容，还关联了使用的模型、token用量、父消息ID（用于构建对话树），这为未来的功能（如对话分析、成本统计）留下了空间。

“自动压缩”（Auto Compact）功能是应对长上下文模型的巧妙设计。像Claude 3.7 Sonnet这样的模型可能有200K的上下文窗口，但费用高昂。OpenCode会监控当前会话的token使用量，当接近阈值（默认95%）时，它会自动触发一个后台任务：请求AI对当前冗长的对话进行智能总结，然后将这个总结作为新会话的初始消息，并关闭旧会话。这样，你既保留了关键的上下文信息，又能继续对话而不会触发“上下文溢出”错误，同时还节省了token成本。你可以在配置中关闭这个功能，但对于进行深度、长周期编码会话的用户来说，这几乎是必选项。

3. 从零开始：安装、配置与核心功能实战

3.1 多种安装方式与选择建议

官方提供了几种安装方式，各有优劣，我结合自己的体验给出建议。

首选：使用安装脚本（Linux/macOS）

curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

这是最快捷的方式。脚本会自动检测你的系统架构，下载最新的预编译二进制文件，并将其安装到/usr/local/bin（可能需要sudo权限）或~/.local/bin。对于大多数想快速上手的用户，推荐这个方法。如果你想安装特定版本，可以设置VERSION环境变量。

次选：Homebrew（macOS/Linux）

brew install opencode-ai/tap/opencode

如果你已经是Homebrew用户，这是最“原生”的体验。Homebrew会帮你管理依赖和更新。但需要注意的是，Homebrew仓库的版本更新可能比GitHub Release稍慢一两天。

高级用户：从源码构建

git clone https://github.com/charmbracelet/crush.git # 注意仓库已迁移 cd crush go build -o crush .

这要求你本地有Go 1.24+环境。从源码构建的好处是你可以随时切换到特定的提交（git checkout），或者为了方便调试而添加一些自己的打印语句。对于想要贡献代码或深度定制的开发者，这是必经之路。

避坑提示：如果你从源码构建，务必注意项目已从opencode-ai/opencode迁移至charmbracelet/crush。克隆旧仓库的代码可能无法构建或缺少最新功能。构建前请仔细阅读仓库的README，确认Go版本和可能的依赖（如C库）。有时你需要运行go mod download和go mod tidy来确保依赖项正确。

Arch Linux用户可以直接通过AUR安装，如yay -S opencode-ai-bin。Windows用户目前没有官方的预编译包，需要通过WSL使用Linux版本，或者从源码为Windows交叉编译（GOOS=windows GOARCH=amd64 go build）。

安装完成后，在终端输入opencode或crush（取决于你安装的版本名），如果看到TUI界面成功启动，恭喜你，第一步完成了。

3.2 深度配置指南：打造你的专属AI工作流

安装只是第一步，合理的配置才能让OpenCode/Crush发挥最大威力。配置文件默认位于~/.config/opencode/.opencode.json（遵循XDG规范）或~/.opencode.json。

1. 配置API密钥与提供商这是最关键的一步。你至少需要配置一个可用的AI提供商。我建议从你已有的服务开始，比如OpenAI或Anthropic。

{ "providers": { "openai": { "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "disabled": false }, "anthropic": { "apiKey": "sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "disabled": false }, "groq": { "apiKey": "gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "disabled": false } } }

安全警告：永远不要将真实的API密钥提交到版本控制系统！配置文件应被加入.gitignore。更安全的做法是使用环境变量（如OPENAI_API_KEY）来设置密钥，这样配置文件中可以留空或删除apiKey字段。OpenCode会优先读取环境变量。

2. 精细化配置AI代理（Agents）agents部分允许你为不同类型的任务指定不同的模型和参数。这是OpenCode非常强大的一个特性。

{ "agents": { "coder": { "model": "claude-3.7-sonnet", "maxTokens": 8000, "temperature": 0.2 }, "task": { "model": "claude-3.5-haiku", "maxTokens": 4000 }, "title": { "model": "gpt-4o-mini", "maxTokens": 80 } } }

coder代理：用于主要的代码生成、解释和调试任务。我通常为它分配能力最强、上下文最长的模型（如Claude 3.7 Sonnet），并设置较低的temperature（如0.2）以保证代码输出的确定性和准确性。
task代理：用于处理一些简单的、不需要深度推理的任务，比如总结文件内容、生成简单的脚本。我会分配一个更快、更便宜的模型（如Claude Haiku或GPT-4o mini）。
title代理：用于自动为会话生成标题。这是一个轻量级任务，所以用最小、最快的模型即可。

你可以在运行时通过Ctrl+O快捷键切换模型，但为不同代理预设模型能让工具更智能地分配资源。

3. Shell配置的玄机默认情况下，OpenCode使用$SHELL环境变量指定的Shell，如果没有设置，则回退到/bin/bash。但你可以通过配置进行精细化控制：

{ "shell": { "path": "/bin/zsh", "args": ["-l", "-i"] } }

"path": 指定Shell的绝对路径。如果你主要使用Zsh并配置了大量插件和别名，这里指定Zsh至关重要，否则AI执行的命令可能无法识别你的别名或函数。
"args": 传递给Shell的参数。
- -l（login shell）：确保Shell会读取你的登录配置文件（如~/.zshrc或~/.bash_profile），这样你的环境变量、PATH、别名就都生效了。
- -i（interactive shell）：启用交互模式。这对于一些需要交互的脚本或命令是必要的，但请注意，这可能会让AI命令在等待用户输入时挂起。通常只使用-l就足够了。

4. 启用调试与日志当你遇到问题时，调试信息是无价之宝。

{ "debug": true, "debugLSP": false }

"debug": true：会在~/.local/state/opencode/logs（或$XDG_STATE_HOME指定目录）下生成详细的日志文件，记录所有HTTP请求、响应、工具调用等。对排查API调用失败、工具执行错误非常有帮助。
"debugLSP": true：会打印Language Server Protocol通信的所有原始数据，信息量巨大，通常只在开发LSP集成功能时才需要开启。

5. 项目级配置的妙用你可以在任何项目的根目录创建一个.opencode.json文件。这个文件的配置会覆盖你的用户全局配置。这太有用了！

场景一：为特定项目指定模型。某个遗留项目代码复杂，你需要Claude 3.7 Sonnet的深度推理能力；而另一个新项目很简单，用GPT-4o mini就够了。
场景二：设置项目特定的命令（后面会详述）。
场景三：禁用某些工具。如果你在一个非常敏感的生产目录下工作，可能想临时禁用write（写文件）工具，防止误操作。

3.3 核心功能实战演练

配置好后，让我们启动OpenCode (opencode)，进入其TUI主界面。界面通常分为三栏：左侧是会话列表，中间是消息历史，底部是输入编辑器。

基础对话：就像和ChatGPT聊天一样，直接在底部输入你的问题，按Ctrl+S或Enter发送。例如：“帮我写一个Python函数，计算斐波那契数列的第n项。” AI会回复代码，并且代码块会自动高亮。

使用工具——让AI“动手”：真正的威力在于工具调用。试着问：“查看当前目录下所有Go文件的列表。” AI可能会决定使用ls或glob工具。它会向你申请权限，你同意后，它就会执行ls *.go或类似的命令，并将结果呈现在对话中。你不需要自己敲命令。

更强大的例子：“帮我找出项目里所有调用了fmt.Printf但格式字符串和参数数量不匹配的地方。” AI可以组合使用grep（搜索）和bash（运行自定义脚本）工具来完成这个复杂的代码审查任务。

会话管理：按Ctrl+N创建新会话。每个会话都是独立的上下文。你可以为不同的任务（如“调试身份验证模块”、“设计数据库Schema”）创建不同的会话。按Ctrl+A可以在会话间快速切换。所有会话都会自动保存。

非交互模式（脚本化使用）：这是OpenCode区别于Web应用的另一大亮点。

# 快速询问一个技术问题，答案直接输出到终端 opencode -p "Golang中context.WithTimeout和context.WithDeadline的区别是什么？" # 将AI输出直接用于脚本 NEW_FUNCTION=$(opencode -p -q "为这个API端点写一个Go函数签名：GET /api/users/{id}，返回JSON") echo "$NEW_FUNCTION" >> handler.go # 以JSON格式获取结构化输出，便于其他程序解析 opencode -p -f json "列出Linux中查看系统负载的三个命令"

-q参数用于关闭执行时的旋转提示符，这在脚本中非常有用，可以保持输出干净。

4. 高级功能与生态集成详解

4.1 自定义命令（Custom Commands）：打造你的效率武器库

自定义命令是OpenCode/Crush中我最喜欢的功能，它让你能将复杂的、重复性的提示词工作流固化下来，一键执行。

创建你的第一个命令假设我经常需要让AI为我新启动的项目生成一个标准的README文件结构。我不需要每次都手动输入“请根据当前项目语言和结构，生成一个专业的README.md，包含...”。我可以创建一个命令。

创建命令文件：

mkdir -p ~/.config/opencode/commands vim ~/.config/opencode/commands/generate-readme.md

编辑文件内容：

# 生成项目README 请分析当前目录下的项目结构、主要语言和可能的依赖，为我生成一个专业、全面的README.md文件。需要包含以下章节： 1. 项目名称与简介 2. 功能特性 3. 安装步骤 4. 使用方法 5. 配置说明 6. 贡献指南 7. 许可证 请先使用工具查看项目文件，再开始撰写。

在OpenCode中，按下Ctrl+K打开命令对话框，你应该能看到一个名为user:generate-readme的命令。选择它，AI就会开始执行你预设的复杂任务。

使用命名参数实现动态命令命令的真正威力在于参数化。比如，我经常需要基于GitHub Issue来编写代码。

# 处理Issue $ISSUE_NUMBER 首先，获取Issue #$ISSUE_NUMBER的详细信息。 RUN gh issue view $ISSUE_NUMBER --json title,body,comments,labels 然后，请分析Issue描述，并给出实现方案。如果需要查看相关代码，请告诉我。

当运行这个user:process-issue命令时，OpenCode会弹出一个输入框，让我填写ISSUE_NUMBER的值。然后，$ISSUE_NUMBER占位符会被我输入的值（比如42）替换。这个值可以在命令中多次引用。

项目级命令与团队协作你可以在项目根目录创建.opencode/commands/目录，里面的命令会带有project:前缀。这非常适合团队协作。你可以把项目常用的代码审查提示、数据库迁移检查提示等作为命令文件提交到仓库中，团队所有成员安装OpenCode后，就能共享同一套高效的AI工作流。

内置命令

Initialize Project：这是一个智能命令。它会扫描你的项目目录，识别项目类型（Go/Node.js/Python等），分析关键文件（go.mod， package.json， README等），然后生成或更新一个OpenCode.md文件。这个文件作为项目的“记忆”，后续的AI会话可以从中读取项目上下文，让AI更了解你的代码库。
Compact Session：手动触发会话压缩。当一次长对话让你觉得混乱时，可以运行此命令，让AI帮你总结当前会话，并开启一个干净的新会话。

4.2 MCP（模型上下文协议）集成：扩展AI的能力边界

MCP是一个新兴的开放协议，旨在为AI模型提供一种标准化的方式来访问外部工具、数据和服务。OpenCode/Crush内置了MCP客户端，这意味着它可以连接到你配置的任何MCP服务器，从而获得新的工具。

MCP能做什么？假设你有一个MCP服务器连接了公司的Jira系统，那么OpenCode中的AI就可以通过这个服务器“看到”并操作Jira任务。或者一个连接了数据库的MCP服务器，可以让AI直接查询数据。社区已经有很多有趣的MCP服务器，比如：

连接文件系统的（OpenCode内置工具已覆盖部分）
连接Git仓库的
连接网页搜索的
连接日历和邮件的

如何配置一个MCP服务器？以连接一个本地的“天气”MCP服务器（假设）为例：

{ "mcpServers": { "local-weather": { "type": "stdio", "command": "/path/to/weather-mcp-server", "args": ["--api-key", "your-key"] }, "company-jira": { "type": "sse", "url": "https://internal-mcp.example.com/jira", "headers": { "Authorization": "Bearer your-jira-token" } } } }

配置完成后，重启OpenCode，AI助手就会自动发现这些新工具。当你问“我今天的日程安排是什么？”或“查询一下北京明天的天气”，AI可能会调用对应的MCP工具来获取答案。

注意事项：MCP工具和内置工具一样，受权限控制。首次调用时会请求你的许可。请确保你信任所连接的MCP服务器，因为它可能具有很高的数据访问权限。

4.3 LSP（语言服务器协议）集成：让AI“理解”你的代码

LSP是编辑器（如VSCode、Neovim）为编程语言提供智能感知（补全、跳转、错误提示）的标准协议。OpenCode集成LSP，主要目的是让AI能获取到代码的诊断信息。

配置LSP你需要为每种语言单独配置其语言服务器。

{ "lsp": { "go": { "disabled": false, "command": "gopls", "args": [] }, "python": { "disabled": false, "command": "pylsp" }, "javascript": { "disabled": false, "command": "typescript-language-server", "args": ["--stdio"] } } }

你需要确保这些语言服务器命令（gopls，pylsp）已经在你的系统PATH中。通常可以通过包管理器安装（如go install golang.org/x/tools/gopls@latest，pip install python-lsp-server）。

LSP的实际效用配置并启用后，当你让AI“检查当前Go文件的语法错误”时，AI可以使用diagnostics工具。该工具会通过LSP客户端请求当前文件的诊断信息，然后将编译器或linter报出的错误、警告列表返回给AI。AI可以据此提供更精准的修复建议。

目前，LSP集成主要暴露了诊断功能。像代码补全、悬停提示等更丰富的功能在客户端已有实现，但尚未完全暴露给AI工具层。不过，仅诊断功能就已经非常有价值，它让AI的代码建议能结合具体的编译错误，而不仅仅是基于文本模式的猜测。

4.4 使用自托管模型

对于注重隐私、希望控制成本或想尝试最新开源模型的开发者，OpenCode支持连接自托管的、提供OpenAI兼容API的模型服务。

1. 通过环境变量配置这是最简单的方式，适用于临时测试或全局使用某个自托管端点。

export LOCAL_ENDPOINT=http://localhost:8080/v1 opencode

启动后，OpenCode会向http://localhost:8080/v1发送请求，并尝试从该端点获取可用的模型列表。你的自托管服务（如Ollama、LocalAI、vLLM等）需要提供类似于OpenAI的/v1/models和/v1/chat/completions端点。

2. 通过配置文件指定具体模型如果你想在多个自托管模型间选择，或者给自托管模型起一个易记的名字，可以在agents中直接配置。

{ "agents": { "coder": { "model": "local:my-llama", "baseURL": "http://localhost:11434/v1", "maxTokens": 4096 } } }

这里model字段的local:前缀是一个命名空间，my-llama是你自定义的名称。baseURL指向你的API端点。在模型选择对话框（Ctrl+O）里，你就能看到my-llama这个选项。

实战经验：使用Ollama时，通常运行ollama run llama3.2会启动一个本地服务。Ollama默认的API地址是http://localhost:11434，其OpenAI兼容端点是/v1。因此，在OpenCode中，你需要将LOCAL_ENDPOINT设置为http://localhost:11434/v1，或者像上面那样在配置中指定baseURL。启动OpenCode后，你应该能在模型列表里看到llama3.2。

5. 常见问题、故障排查与性能调优

即使设计再精良的工具，在实际使用中也会遇到各种问题。下面是我在长期使用中总结的一些常见坑点及其解决方案。

5.1 安装与启动问题

问题1：安装脚本执行失败，提示“Permission denied”或“Command not found”。

原因：安装脚本默认尝试将二进制文件复制到/usr/local/bin，需要sudo权限。或者你的~/.local/bin不在PATH中。
解决：
1. 使用sudo运行脚本：curl ... | sudo bash。
2. 或者，手动下载二进制文件并放到PATH中的目录：
```
curl -L https://github.com/charmbracelet/crush/releases/latest/download/crush_linux_amd64.tar.gz -o crush.tar.gz tar -xzf crush.tar.gz sudo mv crush /usr/local/bin/ # 或 mv crush ~/.local/bin/
```
3. 确保~/.local/bin在你的PATH中：echo $PATH查看，如果没有，在~/.bashrc或~/.zshrc中添加export PATH="$HOME/.local/bin:$PATH"。

问题2：启动OpenCode后，TUI界面乱码或渲染异常。

原因：终端模拟器不支持完整的Unicode字符或True Color，或者TERM环境变量设置不正确。
解决：
1. 尝试使用更现代的终端，如Alacritty、WezTerm、Kitty或iTerm2。
2. 确保你的终端支持True Color。可以运行echo $COLORTERM，如果输出truecolor或24bit则支持。
3. 检查TERM变量：echo $TERM。对于现代终端，通常是xterm-256color或tmux-256color（如果在tmux内）。如果不正确，可以在Shell配置文件中设置，例如export TERM=xterm-256color。
4. 如果是在SSH远程会话中，确保客户端和服务器端的TERM设置一致。

5.2 API与网络连接问题

问题3：配置了API密钥，但AI无法响应，提示“Provider not available”或超时。

排查步骤：
1. 检查密钥格式：确保API密钥正确无误，没有多余的空格或换行。特别是从网页复制时，容易带上不可见字符。
2. 检查提供商开关：确认配置中对应提供商的"disabled": false。
3. 启用调试模式：在配置中设置"debug": true，重启OpenCode，然后查看日志文件（通常在~/.local/state/opencode/logs/）。日志会详细记录HTTP请求和响应，是定位问题的关键。常见的错误有：401 Unauthorized（密钥错误）、429 Too Many Requests（速率限制）、Connection refused（网络问题）。
4. 环境变量覆盖：如果你同时设置了环境变量和配置文件，环境变量优先级更高。检查是否有冲突的环境变量。
5. 代理设置：如果你在网络受限的环境中使用，可能需要为OpenCode配置HTTP代理。Go程序通常遵循HTTP_PROXY和HTTPS_PROXY环境变量。例如：export HTTPS_PROXY=http://127.0.0.1:7890。

问题4：使用GitHub Copilot时，提示“无法认证”或“找不到token”。

原因：Copilot集成需要从本地Copilot插件（VSCode、Neovim等）或ghCLI的缓存中获取GitHub令牌。
解决：
1. 确保你已在其中一个支持的客户端中登录了GitHub并启用了Copilot。
2. 检查令牌文件是否存在：
  - ~/.config/github-copilot/hosts.json
  - $XDG_CONFIG_HOME/github-copilot/hosts.json
3. 如果文件不存在，尝试在VSCode或ghCLI中重新登录/授权Copilot。
4. 你也可以手动创建个人访问令牌（PAT），并赋予copilot权限，然后将其设置为GITHUB_TOKEN环境变量或直接写在配置文件的providers.copilot.apiKey中。

5.3 工具执行与权限问题

问题5：AI尝试执行bash命令或write文件时，权限请求对话框没有弹出，或者操作失败。

原因：可能处于非交互模式（-p），或者工具执行本身出错。
解决：
1. 在交互式TUI中，高危操作一定会弹出权限对话框。如果没弹出，检查是否在对话框打开时误按了Esc键取消。
2. 查看日志。工具执行的命令、退出码、标准输出和错误输出都会记录在调试日志中。例如，一个bash命令失败，日志会显示具体的错误信息（如“command not found”）。
3. Shell配置问题：这是最常见的原因之一。如果AI执行的命令依赖于你的Shell别名或特定环境变量，但OpenCode使用的Shell没有加载你的配置文件，命令就会失败。务必在配置中正确设置shell.path和shell.args（如["-l"]），确保它是一个登录Shell。

问题6：glob或grep工具找不到预期的文件。

原因：工具执行的工作目录可能不是你期望的项目根目录。
解决：OpenCode启动时，其工作目录是你运行opencode命令的目录。你可以使用-c参数指定工作目录：opencode -c /path/to/your/project。在TUI中，你也可以通过命令或让AI使用bash工具执行pwd来确认当前目录。

5.4 性能与成本优化技巧

技巧1：模型选型策略

日常对话与简单任务：使用gpt-4o-mini、claude-3-5-haiku或gemini-2.0-flash。它们响应快，成本极低。
复杂代码生成与调试：切换到claude-3.7-sonnet或gpt-4.1。虽然慢且贵，但推理能力和代码质量显著更高。
本地开发：对于无网络或隐私要求高的场景，使用Ollama运行codellama、deepseek-coder或qwen2.5-coder等代码专用模型。速度取决于你的硬件。

技巧2：善用“自动压缩”和手动会话管理

对于长周期任务（如设计一个系统架构），开启autoCompact。当对话过长时，AI会自动生成摘要并开启新会话，既能保留核心上下文，又能节省token，避免达到模型上下文上限。
对于短平快的任务，主动创建新会话（Ctrl+N）。保持会话主题单一，这样AI的上下文更专注，效果更好。

技巧3：编写高效的自定义命令

在自定义命令中，优先使用RUN（执行命令）和READ（读取文件）等指令来为AI提供精确的上下文，而不是用自然语言描述。例如，与其说“看看main.go里有什么”，不如直接在命令文件中写READ main.go。
对于需要多步交互的任务，可以设计成链式命令。第一个命令负责收集信息（如RUN git diff，READ design.md），第二个命令基于这些信息执行具体操作。

技巧4：控制Token使用

在agents配置中为不同任务设置合理的maxTokens。对于标题生成，80足够；对于代码生成，4000-8000是常见范围；对于深度分析，可以设得更高，但要警惕成本。
如果发现AI回复经常被截断，可能是maxTokens设置太小，或者上下文已满（检查是否触发了自动压缩）。

5.5 已知限制与未来展望

当前限制

LSP功能有限：目前主要利用LSP进行诊断，更强大的功能如代码补全、重构建议尚未深度集成。
多文件编辑体验：虽然可以查看和编辑多个文件，但在TUI中同时处理多个文件的体验不如成熟的IDE流畅。
复杂UI操作：对于需要复杂视觉呈现的任务（如图表生成、复杂表单），终端TUI有其天然局限。
对模型提示词的掌控：高级用户可能希望自定义系统提示词（System Prompt）来更精细地引导AI行为，目前这部分是内置的，未开放配置。

生态与未来项目迁移到Charm团队下并更名为Crush，是一个积极的信号。Charm团队以开发高质量的终端工具（如Glamour， Bubble Tea， Gum）而闻名，他们的维护意味着更可持续的发展和更紧密的终端开发生态集成。可以期待未来与Charm其他工具（如用于脚本的Gum）有更深度的结合，以及更稳定、功能更丰富的版本发布。

对于开发者而言，OpenCode/Crush代表了一种趋势：将强大的AI能力深度集成到开发者原有的、高效的核心工作流（终端+编辑器）中，而不是让开发者去适应一个全新的、笨重的AI工具。它可能不会完全替代Cursor或GitHub Copilot，但它为那些追求效率、热爱终端、重视工作流连贯性的开发者，提供了一个极其锋利和顺手的“副驾驶”。