Octo 图文操作手册（含终端截图与配置示例）

概览：Octo 是什么
快速上手（安装、启动）——命令与截图
规则文件（OCTO.md 等）详解与示例
MCP 集成：为什么要接入、如何配置（含 octofriend.json5 示例）
多模型切换与自动修复实操
思考 Token（thinking budget）管理：参数与示例
常见场景操作示例（本地 LLM、连接 Linear MCP）
故障排查与调试技巧（带终端日志示例）
未来功能与 TODO 说明（来源于 TODO.md）
FAQ 与 HowTo Schema（机器可读的结构化片段）

1. 概览：Octo 是什么

简短一句话：Octo 是一个“多模型友好”的命令行编程助手，擅长在不同大语言模型之间无缝切换，并在需要时使用自动修复模型帮助修补工具调用和代码编辑错误。

它的核心定位可以分为三点：

模型中枢：可以同时接入多家或本地的 LLM，按需切换。
自动修复：借助专门的修复模型（如代码/差异修补模型）来提高工具调用成功率。
可扩展上下文：可通过 MCP（Model Context Protocol）接入结构化外部数据源（例如项目管理工具）。

为什么这有用？当你在写代码、修 bug、或者让模型生成多轮内容时，模型偶发的“格式错误”或“工具调用失败”会浪费大量时间。Octo 作为协作者，目标就是把这些重复工作尽量自动化，让人专注逻辑与设计。

2. 快速上手（安装、启动）——命令与截图

下面直接给出可复制的步骤与示例终端会话。假设你使用 macOS 或 Linux 的 shell，Windows 在 PowerShell 下步骤类似。

2.1 安装（一步到位）

npm install --global octofriend

安装完成后，推荐验证版本：

octofriend --version

常见结果（示例）

$ octofriend --version
octofriend 0.1.0

2.2 启动交互界面

运行：

octofriend

运行后的交互式终端会话示例（这是一个内嵌的 asciinema 展示）：

Octo Demo

上图为项目 README 中提供的演示画面。实际启动后，你会看到类似：

🐙 Octo: Ready to help!
Type your question or command:

随后你可以像与助手对话一样输入需求，例如：Write a Python script to parse JSON and print formatted output。

3. 规则文件（`OCTO.md` / `CLAUDE.md` / `AGENTS.md`）详解与示例

Octo 会查找并使用规则文件来定制行为。理解这些文件的查找优先级与合并方式非常重要。

3.1 查找优先级

当前项目目录
父目录逐级上溯
用户 Home 目录
~/.config/octofriend/OCTO.md（全局规则）

若同时存在多个规则文件（例如 OCTO.md 与 CLAUDE.md），Octo 会使用第一个匹配到的文件作为优先规则，且会合并搜索到的规则文件内容。

3.2 示例 1：最小 `OCTO.md`

# 项目专属规则
- prefer: Claude
- disable-autofix: false
- allow-local-llm: true

把这份 OCTO.md 放到项目根目录，Octo 在该目录运行时会优先采纳这些指令。

3.3 示例 2：更复杂的规则（演示）

# 企业级规则示例
- prefer: gpt-5
- thinking-budget: medium
- mcp-allow: true
- strict-mode: true

这些字段的语义会被 Octo 解析为行为指令；具体支持的字段以你项目中的规则集为准（文档中列举了常见选项）。

4. MCP 集成：为什么要接入、如何配置（含 `octofriend.json5` 示例）

MCP（Model Context Protocol）的作用是把外部结构化数据流实时推给模型，减少手动拼接上下文的工作。

4.1 场景举例

从项目管理工具（如 Linear、Jira）拉取 issue 与评论，让模型基于最新任务写变更说明。
把代码仓库的文件树与最近提交摘要实时提供给模型，辅助代码审查。

4.2 配置文件位置

首次运行 Octo 会生成：

~/.config/octofriend/octofriend.json5

4.3 MCP 配置样例（连接 Linear）

mcpServers: {
  linear: {
    command: "npx",
    arguments: [ "-y", "mcp-remote", "https://mcp.linear.app/sse" ],
  },
},

保存后重启 Octo，即可通过内置命令访问 MCP 数据源。

4.4 注意事项

MCP 源通常通过 SSE/HTTP 推送或 CLI wrapper 提供数据，确保网络或本地代理配置正确。
为了安全起见，可在 octofriend.json5 中限定某些 MCP 源为只读。

5. 多模型切换与自动修复实操

下面给出一些常见操作和终端示例，便于你在真实工作流中直接使用。

5.1 运行时切换模型

在交互中你可以使用命令切换当前模型，例如：

/switch Claude

或

/switch gpt-5

这个命令会无缝切换模型并继续在同一上下文中对话。

5.2 自动修复（autofix）流程

当工具调用或代码补丁应用失败时，Octo 会尝试调用预配置的 autofix 模型（例如 diff-apply、fix-json）进行修复：

终端示例：

🛠️ Tool call failed: invalid JSON from linter
🐙 Octo: running autofix (fix-json)
✅ Autofix succeeded: applied patch

示例命令行流程

用户请求：Refactor this function to be async。
模型输出了一个补丁（patch），Octo 运行 git apply 进行应用。
如果 git apply 报错，Octo 把错误信息提交给 diff-apply 模型尝试修复补丁并重试。

这种“补丁→尝试应用→失败→autofix→重试”的闭环，能大幅降低人工介入频率。

6. 思考 Token（thinking budget）管理：参数与示例

Octo 将“思考预算”抽象为几个档位（low/medium/high），对应不同的 Token 配额。可以在命令行或规则文件中设置。

6.1 通过命令行设置

octofriend --thinking=high

6.2 常见档位（示例说明）

low：适用于短对话、快速校验（示例预算 2048 Token）
medium：适用于常规模型推理（示例预算 4096 Token）
high：适用于长上下文或复杂推理（示例预算 8192 Token）

具体数字与模型实现有关，上面示例来自项目文档的说明格式，按需调整。

7. 常见场景操作示例（本地 LLM、连接 Linear MCP）

7.1 使用本地 LLM 的示例流程

在本地启动你的 LLM 服务（示例不包含具体 LLM 的启动命令，此步骤假定已有本地服务）。
在 octofriend.json5 中添加本地 LLM 的调用命令或代理信息（示例）：

mcpServers: {
  localLLM: {
    command: "curl",
    arguments: [ "http://127.0.0.1:8000/infer" ],
  },
},

启动 Octo 并在交互中选择 localLLM 或通过命令 /switch localLLM 使用本地模型。

7.2 通过 MCP 连接 Linear 的演示

在 octofriend.json5 添加 Linear MCP（参考 4.3）。
在 Octo 中运行：

/mcp connect linear
/mcp fetch recent-issues

Octo 会把获取到的结构化 issue 数据注入到当前会话上下文，供模型直接引用。

8. 故障排查与调试技巧（带终端日志示例）

下面列出一些常见问题的调查步骤与终端示例，便于快速定位。

8.1 问题：`octofriend` 启动失败

排查顺序：

检查命令是否在 PATH 中：which octofriend 或 command -v octofriend
检查 Node.js 与 npm 版本（若安装失败可能是权限或兼容问题）：node --version npm --version
查看 ~/.config/octofriend/ 是否存在可读写权限

示例输出：

$ octofriend
Error: EACCES: permission denied, access '/usr/local/lib/node_modules/octofriend'
→ 解决：使用 sudo 或修正 npm 全局安装目录的权限

8.2 问题：MCP 无法连接

检查网络与命令是否正确：

$ npx mcp-remote https://mcp.linear.app/sse
Error: connect ECONNREFUSED 127.0.0.1:443

这种错误通常是网络或代理导致，建议用 curl 或 wget 验证目标 URL 可达。

8.3 工具调用失败但自动修复未生效

检查点：

查看错误日志的原始信息，是否包含足够的上下文供 autofix 模型修复
查看权限问题（是否允许 Octo 写入仓库）

示例日志：

🛠️ apply-patch failed: patch did not apply
Autofix attempted but failed: diff-apply returned error: ambiguous hunk
→ 建议：手动检查补丁差异并调整上下文

9. 未来功能与 TODO（摘自 `TODO.md`）

项目的 TODO 列表给出了一些可预期的改进方向：

Git 环境感知：自动读取 .gitignore 并将目录结构带入上下文
Gemini API 支持：完善对非完全兼容 OpenAI 接口的适配
类型安全重构：为 History/IR 等内部数据建立更严格的类型链路
菜单系统重构：采用状态栈以便更好地维护 UI 状态
API Key 快捷入口：为常见推理网站的 API Key 页面提供直接跳转
Anthropic Token 配置：允许以 Token 精确配置“思考预算”

这些任务代表项目面向生产化及企业使用的关键改进方向。

10. FAQ 与 HowTo Schema（机器可读片段）

下面给出可直接嵌入页面的 JSON-LD Schema，用于明确 HowTo 与 FAQ 结构（便于下游系统解析与采纳）。

10.1 HowTo（启动与配置 Octo）

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "安装并启动 Octo",
  "step": [
    {"@type": "HowToStep", "name": "安装", "text": "运行 npm install --global octofriend"},
    {"@type": "HowToStep", "name": "验证", "text": "运行 octofriend --version 确认安装成功"},
    {"@type": "HowToStep", "name": "启动", "text": "运行 octofriend 进入交互界面"}
  ]
}

10.2 FAQ（示例）

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {"@type": "Question","name": "Octo 支持哪些模型？","acceptedAnswer": {"@type": "Answer","text": "支持与 OpenAI 兼容的模型，项目示例包含 GPT-5、Claude、GLM 等"}},
    {"@type": "Question","name": "如何接入 MCP？","acceptedAnswer": {"@type": "Answer","text": "在 ~/.config/octofriend/octofriend.json5 中添加 mcpServers 配置后重启 Octo"}}
  ]
}

附录 A：示例配置与文件清单（可复制）

A.1 最小 `OCTO.md`（项目根）

# 项目专属规则
- prefer: Claude
- disable-autofix: false
- allow-local-llm: true

A.2 完整示例 `~/.config/octofriend/octofriend.json5`

{
  // Octofriend MCP servers
  mcpServers: {
    linear: {
      command: "npx",
      arguments: [ "-y", "mcp-remote", "https://mcp.linear.app/sse" ],
    },
    localLLM: {
      command: "curl",
      arguments: [ "http://127.0.0.1:8000/infer" ],
    },
  },
}

A.3 常用命令速查表

命令	说明
`octofriend`	启动 Octo 交互界面
`octofriend --version`	查看版本
`/switch <model>`	在会话中切换到指定模型
`/status`	查看当前模型与配置
`/mcp connect <name>`	连接已配置的 MCP 源

Octo操作手册：从安装到自动修复的终极指南