首页文档OctoHz MCPOctoHz MCP 使用教程

OctoHz MCP 使用教程

OctoHz 提供了一个远程 MCP（Model Context Protocol）server，让 Claude、Codex 等任何兼容 MCP 的智能体客户端可以直接读写项目归档、待办、密码库/主机/API 密钥、公开文档、私有文档、站内内容的发现与发布、导航书签、私人与站内公共资源库，不需要单独装 CLI 或自己写 HTTP 客户端代码。命理玄学（八字/风水/经文/咒语）、衣食住行笔记（饭店/食谱/酒店/保健品/旅游/设备）、股票持仓、工作台生成类（带货视频/本地图片/本地视频/元提示词/历史管理）这些个人数据/生成操作 2026-10-02 起从 MCP 下线，改走 octohz CLI——技术上随时可以恢复，只是日常远程智能体很少用到，为省每轮对话的 MCP 工具 token 预算而精简。除了需要读本地仓库文件的 sync 和一次性的 migrate-entries，CLI 的所有命令组在 MCP 里都有对应。

更新日志

2026-10-14：agent_memory 的 list/search/get(概览) 新增 status 过滤——不传 status 时默认把已完成(status=done)的 context 挡在结果外，不然做完的待办会永远堆在列表里；显式传 status=done/pending/in_progress 可以精确查
2026-10-14：新增 agent_memory 工具（记忆空间：核心摘要+六类时间线resource/capability/event/lesson/context/note，show 查看详情自动计数，CLI 对应 octohz agent-memory），24→25 个
2026-10-10：OctoHz CLI/MCP/Publishing/Project 四个 Agent Skill 正式公开发布到官方资源库（/resources?cat=7，任何人可下载）
2026-10-02：修复 project 的 patch action——按 key upsert 的对象数组（tech_stack/servers/env_vars/databases/third_party/cron_jobs/dir_structure.key_paths）之前只能增/改，传完整数组不含某条不会删掉那条；现在支持传 {<key字段>,"$delete":true} 删除单条，不用再整字段传 null 清空重发
2026-10-02：修复 project 的 patch action——definition.tech_stack 之前没有按 key upsert，传 1 条会把其余全部清空；现在按 layer+tech 组合 upsert，跟文档一直写的"已知数组按 key upsert"保持一致（同一个 tech 配不同 layer 算两条不同条目，不会互相覆盖）
2026-10-02：project 的 patch action 新增 ops.servers[].services/ops.local_dev/ops.deploy_flow 增量合并——这三个无 key 的字符串数组除了传完整数组整体替换外，现在也支持传 {"$add":[...]}/{"$remove":[...]} 包装对象只增/只删一部分，不用先读旧值拼完整数组
2026-10-01：submit_post/product_patch/vest_publish 的 buyText 参数补充「音乐」分类（category=music）用法说明——填网易云/QQ音乐分享链接会自动触发站内播放器
2026-10-01：文档新增 outline/heading/grep 三个可选参数，文档长时不用整篇读；新增 doc_diff 工具看文档自上次编辑或指定时间点以来改了什么
2026-10-01：文档更新支持章节级局部编辑（heading 替换/appendToHeading 追加），改成 PATCH 语义，不传的字段不会被清空
2026-10-01：补充「衣食住行扩展」工具表格（酒店/保健品/旅游/设备），此前漏收录
2026-10-02：MCP 工具改用「一个工具 + action/scope/kind 参数」的调用方式，171→24 个；旧工具名（如 bazi_list/project_task_claim/password_get）全部不再存在；命理玄学/衣食住行/股票/工作台生成类 14 个工具下线，改走 CLI

Endpoint

https://octohz.com/api/mcp

协议：MCP Streamable HTTP（stateless 模式，服务端不维护 session，每次请求独立处理）
只支持 POST（JSON-RPC 2.0）；GET/DELETE 会返回 405
鉴权：Authorization: Bearer <apiToken>——跟 CLI 用的是同一个 token，在账号设置页生成

不带 token 也能调用公开工具（如 doc(scope=public 时的 list/get/diff)、search_content、category_list、site_resource(action=list/get)），但涉及个人数据或写操作的工具必须带 token，否则返回 isError: true，提示"未授权"。

密码库 / 主机 / 我的 API 走的是另一套鉴权：独立的、限次读取的 privateKey（账号设置页单独生成，跟 apiToken 不是一回事）。这套 key 不放在 Authorization header，而是作为 password/host/api 三个工具各自的参数传——因为一次 MCP 连接的 header 是固定的，没法按 tool 切换成两种不同的 token，做成参数就能每次调用显式指定。action=list 免费不耗额度，单条读取（如 password{action:"get"}）消耗 1 次额度，额度耗尽后该 key 自动失效，需要去账号设置页重新生成。vest_publish 的 vestToken（马甲身份）也是同样的理由，同样走参数。

配套 Agent Skill（推荐）：如果你的智能体支持装 Skill，装上 OctoHz MCP Skill 能省掉很多翻文档的功夫——连接方式、鉴权区分、能力概览、贯穿全局的使用惯例，比这份教程更贴近智能体实际调用场景。入口：官方资源库（任何人可浏览下载），同一处还有 CLI / Publishing / Project 三个配套 skill。

接入方式

Claude Code

claude mcp add --transport http octohz https://octohz.com/api/mcp \
  --header "Authorization: Bearer <your-apiToken>"

Codex（桌面版 / CLI）

Codex 的技能（skill）只提供使用说明，不会自动注册 MCP。远程 MCP 要单独写入用户级 ~/.codex/config.toml；官方推荐用 CLI 注册，CLI 与 Codex 桌面版共用这份配置：

codex mcp add octohz `
  --url https://octohz.com/api/mcp `
  --bearer-token-env-var OCTOHZ_API_TOKEN

codex mcp list
codex mcp get octohz

注册后完全退出并重新打开 Codex，再新建任务；已经运行的桌面进程和旧任务不会自动获得新 MCP 工具。设置页“插件 → MCP”中应能看到 octohz。

Windows 上更安全的认证方式

bearer_token_env_var 是标准配置，但本地智能体启动的 shell 子进程也可能继承该环境变量。已经使用 OctoHz CLI 的 Windows 用户，可以改用 Codex 的 http_headers_helper，让 MCP 客户端调用时才从现有 CLI 配置读取 token，避免把 token 放进任务环境。

例如新建 %USERPROFILE%\.octohz\mcp-headers.ps1：

$config = Get-Content -Raw "$env:USERPROFILE\.octohz\config.json" | ConvertFrom-Json
if ([string]::IsNullOrWhiteSpace([string]$config.token)) {
  throw "OctoHz token is not configured"
}
@{ Authorization = "Bearer $($config.token)" } | ConvertTo-Json -Compress

然后在 ~/.codex/config.toml 中配置，并把示例里的 your-name 换成实际 Windows 用户目录名：

[mcp_servers.octohz]
url = "https://octohz.com/api/mcp"
http_headers_helper = 'powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Users\your-name\.octohz\mcp-headers.ps1"'

不要把真实 token 直接写进教程、项目文件、命令历史或可被智能体读取的日志。非交互模式若使用 approval_policy=never，需要审批的 MCP 调用会被拒绝；这是客户端审批策略，不是连接失败。

25 个 Tool 会不会占满上下文

支持 Tool Search 的新版本 Codex 会把 MCP 工具延迟加载：任务启动时只保留很小的发现入口，需要调用时才按需载入匹配工具的 schema，不会把全部 25 个完整 schema 塞进每一轮上下文。

2026-09-23 在 Codex CLI 0.155.0-alpha.16 上做过一组同提示、全新进程的对照测试（当时 MCP 还是 136 个工具，2026-10-02 经四轮调整后数字已变，但延迟加载的结论不受影响）：

状态	首轮 input tokens
启用 OctoHz MCP	15,769
临时禁用 OctoHz MCP	15,763

启动差异只有 6 tokens；随后要求读取公开文档 84 时，事件流才选择对应工具（当时工具名还是 doc_get，现在是 doc{scope:"public",action:"get"}）。这说明该版本没有在新任务启动时全量加载全部工具 schema。不同客户端、模型和版本的实现可能不同；不支持 Tool Search 的客户端仍可能急加载全部工具，可用 enabled_tools 白名单限制暴露范围。

通用 MCP client 配置

大多数支持远程 MCP（HTTP transport）的客户端配置格式类似：

{
  "mcpServers": {
    "octohz": {
      "url": "https://octohz.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-apiToken>"
      }
    }
  }
}

具体字段名以各家客户端文档为准（有的叫 url，有的叫 serverUrl）。注意只有支持 HTTP/Streamable HTTP transport 的客户端能连——纯 stdio 型 MCP 客户端连不了远程 server。

可用 Tool（共 25 个）

验证于 2026-10-14，server 2.11.0。数字以 tools/list 实时结果为准，本节由 tools/mcp/doc-tools-table.ts 生成。

项目归档（apiToken）

Tool	说明	必填参数
`project`	统一管理项目归档本体。action=list(摘要字段)/get(需id;默认摘要索引,full=true完整数据,section 指定只返回definition/status/ops/decisions/pitfalls/design/data_models其一)/add(需name,对应CLI `octohz project add`)/patch(需id,智能合并definition/ops/design文档段,对象深合并,decision/pitfall/task/event用专门tool,对应CLI `octohz project patch`;已知对象数组(tech_stack/servers/env_vars/databases/third_party/cron_jobs/dir_structure.key_paths)按key upsert——只增/改,传完整数组不含某条不会删除该条(这点跟下面服务字符串数组不同),删单条要传{<key字段>,"$delete":true};字段传null删整个字段;ops.servers[].services/ops.local_dev/ops.deploy_flow这三个无key的字符串数组,传完整数组=整体替换(能删),传{"$add":[...]}/{"$remove":[...]}=只增/只删一部分不用先读旧值)/onboard(需id,一次拿definition+onboarding+active决策/坑/开放任务+最近事件+各段新鲜度,新智能体接手项目永远从这个action开始,brief=true返回精简版)。需要 Authorization: Bearer 。	`action`（另有 11 个可选）
`project_entry`	统一读写项目条目（decision/pitfall/task/event/note）本体。action=list(可按kind/status过滤,对应CLI `octohz project entries`)/get(按编号如D003或数字id读完整内容,对应CLI `octohz project entry`)/rm(按编号或数字id删除,对应CLI `octohz project entry-rm`)。新增/编辑用 project_decision/project_pitfall/project_task/project_event 对应的专门 tool。需要 Authorization: Bearer 。	`action`、`id`（另有 3 个可选）
`project_decision`	统一管理决策条目。action=add(服务端分配D编号,对应CLI `octohz project decision add`)/edit(按编号如D003更新,只传的字段会改,supersede=true标记已废弃,对应CLI `octohz project decision edit`)。需要 Authorization: Bearer 。	`action`、`id`（另有 8 个可选）
`project_pitfall`	统一管理坑条目。action=add(服务端分配P编号,对应CLI `octohz project pitfall add`)/edit(按编号如P003更新,只传的字段会改,对应CLI `octohz project pitfall edit`)/resolve(标记已解决,对应CLI `octohz project pitfall resolve`)。需要 Authorization: Bearer 。	`action`、`id`（另有 8 个可选）
`project_task`	统一管理任务条目。action=list(开放任务,all=true含已完成)/add(服务端分配T编号,默认status=pending,对应CLI `octohz project task add`)/claim(置in_progress+记认领人,防止多智能体重复做同一件事,对应CLI `octohz project task claim`)/done(标记done并自动追加一条完成事件到时间线,对应CLI `octohz project task done`)。需要 Authorization: Bearer 。	`action`、`id`（另有 8 个可选）
`project_event`	统一管理交接事件时间线。action=list(最近的在前)/log(新增event条目,服务端自动分配编号并写快照,对应CLI `octohz project log`)/edit(按编号如E003更新,只传的字段会改,原值保留,用于补充/修正已记录事件的内容,不是用来篡改历史,对应CLI `octohz project event edit`)。需要 Authorization: Bearer 。	`action`、`id`（另有 10 个可选）
`project_snapshot`	统一管理项目版本快照。action=list(不含内容,只有id/note/时间)/get(需sid,读完整内容)/restore(需sid,把definition/ops/design文档段恢复到某个历史快照,迁移后的项目条目不受影响,恢复前自动备份当前版本)。需要 Authorization: Bearer 。	`action`、`id`（另有 1 个可选）

密码库（需要 privateKey）

Tool	说明	必填参数
`password`	统一管理密码库。action=list(免费,不含密码字段)/get(需id,消耗1次额度,解密返回)/add(需title/password)/update(需id/title/password,整条覆盖非局部patch)/rm(需id)。需要 privateKey。	`privateKey`、`action`（另有 7 个可选）

主机（需要 privateKey）

Tool	说明	必填参数
`host`	统一管理主机。action=list(免费,不含密码)/get(需id,消耗1次额度)/find(按IP查找,需ip,reveal=true且唯一匹配时才读凭据)/add(需name)/update(需id,局部更新只传的字段会改)/rm(需id)。需要 privateKey。	`privateKey`、`action`（另有 21 个可选）

我的 API（需要 privateKey）

Tool	说明	必填参数
`api`	统一管理第三方 API/服务订阅。action=list(免费,不含apiKey)/get(需id,消耗1次额度)/add(需name/apiKey)/update(需id,只传的字段会改)/rm(需id)。需要 privateKey。	`privateKey`、`action`（另有 9 个可选）

内容发现与发布（混合鉴权）

Tool	说明	必填参数
`util_get_title`	抓取一个 URL，提取	`url`
`category_list`	列出发布内容可用的分类（id/name/slug），发布前先查一下，submit_post 的 category 参数直接用这里的 id 或 slug。无需鉴权。	无
`search_content`	跨类型全文搜索：帖子/论坛/文档/推荐集/资源。带 apiToken 时也能搜到仅会员可见的内容。无需鉴权（不带 token 只搜公开内容）。	`q`（另有 3 个可选）
`product`	统一管理已发布内容。action=get(需id,读正文)/list(按条件过滤)/patch(需id,本人或admin,只传的字段会改)/delete(需id,仅admin,级联清理,不可撤销)。发布用 submit_post，不在这个工具里。	`action`（另有 22 个可选）
`submit_post`	发布一条新内容（推荐/资源等）。category 可传数字 id 或 slug/名称（先用 category_list 查可用值）。封面图传 imageUrl（服务端抓取）或 imageBase64（+可选 imageMimeType）二选一，都不传则无封面图。需要 Authorization: Bearer 。	`name`、`intro`、`category`（另有 7 个可选）
`essay_post`	发一条 essay 类型的短内容（≤100 字，类似推文）。需要 Authorization: Bearer 。	`content`
`vest_publish`	用马甲（vest）身份发布一条内容，跟 submit_post 用 apiToken 发布是同一套发布逻辑，区别是归属和展示身份是马甲而不是本人。vestToken 在 octohz.com/my/vests 获取，作为参数传（不是 Authorization header，理由同 privateKey）。封面图传 imageUrl（服务端抓取）或 imageBase64（+可选 imageMimeType）二选一，都不传则无封面图。	`vestToken`、`name`、`intro`、`category`（另有 6 个可选）

文档（公开 /docs + 我的私有文档，scope 参数区分，混合鉴权）

Tool	说明	必填参数
`doc`	统一管理文档与其分类/文件夹。scope=public(/docs 公开教程,仅管理员可写)/private(我的私有笔记,本人可写,isPublic=true 时任何人可 get)。action=list/get(支持 outline 看目录/heading 取小节/grep 搜正文，省 token)/add/update(content 直传=整篇替换；配 heading=只替换该小节；配 appendToHeading=小节末尾追加)/delete/diff(仅 scope=public，对比历史版本，不传 since 对比最近一次编辑前后)/category_list/category_add(需name;scope=public 仅管理员)/category_patch(需id,仅scope=private)/category_rm(需id,仅scope=private)。需要 Authorization: Bearer （public 的写操作需管理员；get/list/diff/category_list 无需鉴权，除非是非公开的私有文档）。	`scope`、`action`（另有 17 个可选）

待办（apiToken）

Tool	说明	必填参数
`todo`	统一管理我的待办事项。action=list/create(需content)/complete(需id,done 默认true)/update(需id,只传的字段会改)/rm(需id)。需要 Authorization: Bearer 。	`action`（另有 4 个可选）

导航书签（apiToken）

Tool	说明	必填参数
`nav`	统一管理我的导航书签与其分类。action=list/add(需title/url)/patch(需id,只传的字段会改)/rm(需id)/category_list/category_add(需name)/category_rename(需id/name)/category_rm(需id,旗下书签分类会被置空)。需要 Authorization: Bearer 。	`action`（另有 8 个可选）

站内公共资源库（公开读取 / apiToken 写入）

Tool	说明	必填参数
`site_resource`	统一管理官方资源库条目与其分类。action=list(可按categoryId过滤,无需鉴权)/get(需id,含版本历史,无需鉴权)/add(需title/summary,仅管理员)/patch(需id,改元信息,管理员或发布人本人)/publish_version(需id/version,管理员或发布人本人)/downloads(需id,管理员或发布人本人)/rm(需id,仅管理员)/category_list(无需鉴权,含每类资源数)/category_add(需name,仅管理员)/category_patch(需id,改名/置顶/排序,仅管理员)/category_rm(需id,仅管理员)。	`action`（另有 17 个可选）

私人资源库（apiToken）

Tool	说明	必填参数
`resource`	统一管理我的资源库条目与其分类。action=list(可按categoryId过滤)/get(需id,含版本历史)/add(需title/summary)/patch(需id,改元信息,不改版本或文件)/publish_version(需id/version,追加新版本)/downloads(需id,查下载记录)/rm(需id)/category_list(含每类资源数)/category_add(需name)/category_patch(需id,改名/置顶/排序,只传的字段会改)/category_rm(需id)。需要 Authorization: Bearer 。	`action`（另有 18 个可选）

工作台（查余额，apiToken）

Tool	说明	必填参数
`console_balance`	查看工作台余额和今日消耗（元）。工作台 AI 功能按实际消耗扣费，调用前可先查。需要 Authorization: Bearer 。	无

智能互通（查看其他智能体，apiToken）

Tool	说明	必填参数
`agent`	统一查看 OctoHz 智能互通网络里可见的智能体。action=list(自己的+被授权的,精简信息)/get(需agentId,完整信息:连接方式/Agent Card/开放操作范围/能力声明，不含任何密钥)。能力列表是对方自行声明的展示信息，不参与授权。需要 Authorization: Bearer 。	`action`（另有 3 个可选）

记忆空间（apiToken；以某智能体自己的身份操作时传deviceCredential）

Tool	说明	必填参数
`agent_memory`	统一管理智能互通里每个智能体的记忆空间。action=spaces(列出我能读的全部空间,不需要提前知道agentId)/get(需agentId,核心摘要+六类各最近5条概览,只给标题不给全文；context的done条目不出现在这5条里)/list(需agentId,按kind筛选+分页,不传kind看全部,只给标题;sort=visits可看查看次数最高的在前,此时不支持翻页只返回前take条；不传status时已完成的context默认不出现在结果里(退出活跃视图),传status=done可以专门看已完成的)/search(需agentId+q,PG ILIKE关键词子串匹配,覆盖payload里的title/detail/usage/environment/source/goal,是精确子串匹配不是语义搜索,换个说法可能搜不到,结果同样只给标题；status过滤规则同list)/show(需agentId+refId,唯一返回完整payload的地方；每次show会让这条记录的查看次数+1,这不是另外的动作,是看一眼就自动记，想知道自己常用哪些资源就用list的sort=visits看排行)/add(需agentId+kind+payload,kind=resource(资源,可以是文档/网址/API/工具等任何东西,payload可带usage/environment/source/lastVerifiedAt/url,title必填)\|capability(能力,自己写给自己看的"怎么做某事"的笔记，不是AgentHubAgentCapability那套对外声明的协议能力，两者同名不同概念，payload可带detail)\|event(经历,发生过什么,payload可带detail/verified/remaining)\|lesson(教训,从经历提炼出的结论,payload可带detail+可选relatedEvent引用某条经历的refId佐证)\|context(当前状态/待办,agent自己的交接快照,不是模糊的小事，必须是实际需求——要做的功能/要调查的事情，payload的goal字段必填(具体目标是什么)，detail/remaining/blocked可选，status默认pending,可传pending/in_progress/done)\|note(外部留言,payload可带detail),除context外payload都要有title)/edit(需agentId+refId+payload+expectedVersion,context可以额外传status改状态,版本号不对或条目已停用会返回明确错误,不会静默覆盖)/deactivate(需agentId+refId+expectedVersion,软删除不是彻底删除,正文仍保留)/summary_edit(需agentId+summary+expectedVersion,传{identity:"",conventions:[]}即为清空)。resource/capability/event/lesson/context这类"本人记忆"默认以member身份操作(member对自己名下所有agent有完整读写权限，这不是权限漏洞，是设计本身)；要"以某个agent自己的身份"操作(比如sibling agent给别的agent留note、或该agent自己改自己的东西)，必须额外传deviceCredential(该agent claim时拿到的ahd_开头设备凭证)——没传或凭证已失效会直接报错，不会偷偷换成member身份继续执行。需要 Authorization: Bearer 。	`action`（另有 12 个可选）

调用示例

下面先给出一个完整请求模板。替换 name 和 arguments 即可调用其他工具；公开工具或只使用 privateKey 的工具可以省略 Authorization header。

curl -s -X POST https://octohz.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your-apiToken>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "project", "arguments": { "action": "onboard", "id": 1, "brief": true } }
  }'

常用 `params`

接手项目：

{ "name": "project", "arguments": { "action": "onboard", "id": 1, "brief": true } }

认领任务并在完成后写入交接记录：

{ "name": "project_task", "arguments": { "action": "claim", "id": 1, "ref": "T003", "owner": "my-agent" } }
{ "name": "project_task", "arguments": { "action": "done", "id": 1, "ref": "T003", "note": "接入了七牛云 CDN 并验证" } }

按 IP 查找主机凭据（privateKey 是参数，不是 Authorization header）：

{ "name": "host", "arguments": { "action": "find", "privateKey": "<your-privateKey>", "ip": "192.168.1.50", "reveal": true } }

发布带封面的内容；先用 category_list 查询分类：

{
  "name": "submit_post",
  "arguments": {
    "name": "标题",
    "intro": "一句话简介",
    "description": "正文，支持 Markdown",
    "category": "software",
    "buyText": "https://example.com",
    "imageUrl": "https://example.com/cover.png"
  }
}

查工作台余额：

{ "name": "console_balance", "arguments": {} }

新增资源并让服务端抓取文件：

{
  "name": "resource",
  "arguments": {
    "action": "add",
    "title": "标题",
    "summary": "一句话摘要",
    "fileUrl": "https://example.com/package.zip"
  }
}

返回格式

所有 tool 都返回标准 MCP content 数组，正文是 JSON.stringify 后的字符串；失败时 isError: true，content[0].text 是可读的中文错误说明（未授权 / 不存在 / 校验失败 / 额度用完等）。

下一步

OctoHz 智能体接入教程 —— 两步快速上手：装 CLI、装配套 Skill
官方资源库 —— OctoHz MCP/CLI/Publishing/Project 四个配套 Agent Skill，装上能省掉很多翻文档的功夫
OctoHz CLI 使用教程 —— CLI 接入方式的完整命令参考（跟这份 MCP 教程是同一套能力的两种接入方式）
OctoHz 智能互通：Bridge 安装与联调教程 —— 本机智能体互相直连/收发消息
OctoHz 网站介绍 —— OctoHz 是什么

OctoHz MCP 使用教程

OctoHz MCP 使用教程

更新日志

Endpoint

接入方式

Claude Code

Codex（桌面版 / CLI）

Windows 上更安全的认证方式

25 个 Tool 会不会占满上下文

通用 MCP client 配置

可用 Tool（共 25 个）

项目归档（apiToken）

密码库（需要 privateKey）

主机（需要 privateKey）

我的 API（需要 privateKey）

内容发现与发布（混合鉴权）

文档（公开 /docs + 我的私有文档，scope 参数区分，混合鉴权）

待办（apiToken）

导航书签（apiToken）

站内公共资源库（公开读取 / apiToken 写入）

私人资源库（apiToken）

工作台（查余额，apiToken）

智能互通（查看其他智能体，apiToken）

记忆空间（apiToken；以某智能体自己的身份操作时传deviceCredential）

调用示例

常用 params

返回格式

下一步

常用 `params`