local agent field guide / 2026 OPENAI-COMPATIBLE

把模型，
接入你的工作台。

WisCode Agent Model Sync 是一套面向本地 AI Agent 的模型同步与代理工具：自动获取可用模型，启动本地 OpenAI 兼容代理，再把 WorkBuddy、OpenCode、Claude Code 等工具接上。

不需要手工复制上游 API Key · 默认先 dry-run · 配置前自动备份

agent-console / local

# one local bridge, many agents
$ wiscode-agent-model-sync

$ python3 openai_proxy.py \
    --proxy-api-key local-wiscode-proxy

// 127.0.0.1:8788/v1
// models: healthy / synced / ready

✓ WorkBuddy      connected
✓ OpenCode       connected
✓ Claude Code    messages ready

status: protectedno key printed

01本地代理入口

02协议：OpenAI + Anthropic

08+可同步的本地 Agent

0600本地凭据权限（macOS/Linux）

01 / what it solves

先把“能用”
变成“好用”。

你不必为每个 Agent 重复粘贴地址、模型名和 Key。Skill 把模型目录、代理协议、配置写入和验证串成一条可重复的本地工作流。

SYNC / 01模型

动态同步模型目录

从登录态对应的 WisCode 模型套餐读取可用模型和凭据映射，不依赖手工维护清单。

BRIDGE / 02协议

一个本地兼容入口

OpenAI 客户端走 /v1/chat/completions，Claude Code 走原生 /v1/messages。

ROUTE / 03连接

配置 Agent，不改工作习惯

用同步脚本写入目标 Agent 的用户级配置，写入前 dry-run，写入时备份，完成后验证。

GUARD / 04安全

Key 留在本地

完整 Key 不打印、不写入 Agent 配置或日志；代理只从受保护的本地凭据 JSON 读取。

02 / how it works

三步，把模型
送到本地 Agent。

Skill 把“获取凭据”和“使用模型”拆开：同步阶段需要登录态，代理日常只读本地凭据。这让运行时更稳定，也更容易排查。

STEP 01AUTH / SYNC

同步

首次运行设备授权，生成 model-credentials.json，拿到当前账号可用模型。

STEP 02LOCAL / PROXY

启动

本地监听 127.0.0.1:8788，按模型选择套餐 Key，健康检查后暴露模型目录。

STEP 03WRITE / VERIFY

接入

选择 Agent 与模型，先 dry-run，再写入配置并验证；失败时保留备份，方便恢复。

03 / quick start

安装完，
只记住这一句。

把下面这段作为你的首次使用指令交给 Agent。安装完成后，继续让它启动代理、检查健康状态，再配置 WorkBuddy 等本地工具。

BEGINNER FRIENDLY / SAFE BY DEFAULT

安装这个skill https://share.21588.org/-uFFEqQ7eu5/wiscode-agent-model-sync.zip 安装完成后使用 wiscode-agent-model-sync，启动本地 OpenAI 兼容代理，并配置 workbuddy 等本地Agent 工具

01 / 首次准备：同步本地凭据

SKILL_DIR="$HOME/.wiscode/skills/wiscode-agent-model-sync"
python3 "$SKILL_DIR/scripts/sync_credentials.py" --dry-run
python3 "$SKILL_DIR/scripts/sync_credentials.py"

02 / 启动本地 OpenAI 兼容代理

python3 "$SKILL_DIR/scripts/openai_proxy.py" \
  --proxy-api-key local-wiscode-proxy

# default: http://127.0.0.1:8788/v1

03 / 验证代理是否健康

curl --fail-with-body -sS \
  http://127.0.0.1:8788/health

04 / agent matrix

你常用的，
都能接。

每个 Agent 都有独立的同步入口。选一个开始，或用逗号一次配置多个目标。Codex 默认不改，只有明确指定并确认兼容时才处理。

WB推荐入口

WorkBuddy

写入用户级模型目录，保留其他 provider，并设置默认模型。

--agents workbuddy ~/.workbuddy/models.json

OCOPENAI

OpenCode

走本地 OpenAI-compatible provider，适合日常编码和多模型切换。

--agents opencode ~/.config/opencode/opencode.json

CCMESSAGES

Claude Code

保留 Anthropic Messages 协议，代理地址使用根路径。

--agents claude ~/.claude/settings.json

HEAGENT

Hermes

自动写入 Hermes 的用户配置，完成后重启 Hermes 即可读取新模型。

--agents hermes ~/.hermes/config.yaml

MIOPENAI

Mimo

把代理地址与模型配置写入 Mimo 的 JSONC 配置。

--agents mimo ~/.config/mimocode/mimocode.jsonc

PIOPENAI

Pi

同时更新模型目录和 agent settings，适合本地终端工作流。

--agents pi ~/.pi/agent/models.json

OCROUTER

OpenClaw

根据当前配置同步模型与鉴权，持续使用本地代理入口。

--agents openclaw 按当前 OpenClaw 配置写入

DSYAML

DSH

写入 deepseek-official provider，并支持 reasoning effort 档位。

--agents dsh ~/.dsh/settings.yaml

ALOBSIDIAN

Ailu

使用专用脚本接入自定义 Claude provider，凭据进入 SecretStorage。

sync_ailu.py --verify Vault/.obsidian/plugins/ailu

关于 Codex：Skill 默认不修改 Codex 的独立 Responses 配置。只有你明确要求、并确认目标版本 provider 格式兼容时，才建议单独处理。

05 / prompt library

常用操作，
一句一句列好。

下面的提示词可以直接复制给 WorkBuddy、Claude Code 或其他本地 Agent。建议先让 Agent 解释 dry-run 结果，再确认正式写入。

P01安装并完成首次配置

适合第一次安装，要求 Agent 不跳过预览与验证。

P02查看当前可用模型

让 Agent 只读取模型目录，不修改任何配置。

请使用 wiscode-agent-model-sync 列出当前账号可用模型，说明每个模型的 ID，并且不要打印任何完整 API Key，也不要修改 Agent 配置。

P03刷新模型凭据

登录态失效或模型套餐变化时使用。

请先用 dry-run 检查 wiscode-agent-model-sync 的凭据同步结果；如果需要浏览器授权，请只返回授权地址，不要输出 token 或 API Key。确认后刷新本地模型凭据，并告诉我需要重启哪个代理。

P04启动并检查本地代理

让 Agent 负责启动、健康检查和模型目录确认。

请启动 wiscode-agent-model-sync 的本地 OpenAI 兼容代理，监听 127.0.0.1:8788；启动后调用 /health 和 /v1/models 验证，并只报告状态、模型数量和错误摘要，不要输出任何完整密钥。

P05配置 WorkBuddy

最常用的本地工作台接入方式。

请使用 wiscode-agent-model-sync 把 deepseek/deepseek-v4-flash 配置到 WorkBuddy，使用本地代理和 local-wiscode-proxy。先执行 dry-run，确认后正式写入并 verify，保留其他 provider，并说明修改了哪些文件。

P06一次配置多个 Agent

适合把同一模型分发给多套本地工具。

请把 WisCode 模型同步到 WorkBuddy、OpenCode、Mimo、Pi 和 OpenClaw。先检测目标配置是否存在，执行 dry-run，确认后才写入；所有已有配置先备份，最后逐个 verify。

P07设置登录自启动

macOS / Windows 登录后自动让代理可用。

请检查 wiscode-agent-model-sync 的 autostart 状态。先展示 install --dry-run 结果，确认后安装当前用户级自启动，并告诉我生成的服务文件位置；不要写入任何上游 API Key。

P08排查 401 / 429 / 5xx

把“Key 失效”和“上游暂时不可用”分开诊断。

请排查本地代理请求失败：分别检查 /health、/v1/models、代理日志和上游状态。区分 401/402/403/429 与网络错误/5xx；不要把完整 API Key 打印出来，也不要未经确认删除凭据。

P09配置 Claude Code / Ailu

需要原生 Anthropic Messages 协议时使用。

请把 Claude Code 指向 wiscode-agent-model-sync 的本地 Anthropic Messages 代理；不要把 /v1 重复拼到 ANTHROPIC_BASE_URL。配置 Ailu 时优先使用 sync_ailu.py 和 Obsidian SecretStorage，并验证原生流式响应。

P10切换模型并验证

切换前先确认模型是否真的在本地目录中。

请将默认模型切换为 z-ai/glm-5.2。先列出本地代理 /v1/models 确认模型存在，再执行 dry-run，正式写入后用最小请求回复 pong 验证；如果模型容量已满，给出替代模型。

06 / screenshot slots

操作截图。

WorkBuddy 中输入 wiscode-agent-model-sync 安装提示词的截图

07 / keep the lights on

如果它帮你省下了一点时间，请我喝杯咖啡。

这个 Skill 的每一次更新，都来自真实使用里的小坑：少复制一次 Key，少改一份配置，少在不同 Agent 之间来回折腾。如果它刚好让你的工作顺了一点，欢迎用一杯咖啡，支持我继续维护、验证和分享。

每一杯咖啡，都会变成下一次更新里的耐心

微信支付收款码，支持作者喝一杯咖啡 — 扫码支持作者 · 谢谢你让这个小工具继续长大

08 / safety by design

把安全，
写进默认值。

这是一个会接触模型凭据的工具，所以“能跑”不是唯一标准。每一个高风险动作都应该可预览、可回滚、可解释。

先 dry-run，再正式写入

预览将修改哪些 Agent 配置，确认后再执行正式同步。

写入前创建带时间戳备份

已有 JSON / YAML / TOML 配置会保留 .wiscode-*.bak，方便恢复。

完整 Key 不出现在输出里

上游模型 API Key 只在本地凭据文件和代理内存中使用，不写入 Agent 配置。

失败 Key 会短暂冷却

401/402/403 默认 15 分钟，429 默认 1 分钟；网络错误和 5xx 不误判为坏 Key。

09 / field notes

遇到问题，
先看这里。

把常见故障分为配置、代理和上游三层，先定位层级，再决定是否刷新凭据或重启服务。

为什么 Agent 配置写入了，但模型没有变化？

先确认目标 Agent 的实际安装路径和配置文件，再重启 Agent。WorkBuddy 读取用户级 models.json；Claude Code 需要重启进程；Ailu 需要保持 Vault 打开并重载插件。

代理启动时报“没有有效模型”怎么办？

先执行 sync_credentials.py 刷新本地模型凭据，再检查 ~/.wiscode/model-credentials.json 的权限与内容是否有效。代理不会从静态环境 Key 或上游 /v1/models 自动补齐。

401、429 和 5xx 的处理方式一样吗？

不一样。401/402/403/429 才会触发 Key 切换与短期冷却；网络错误、超时和 5xx 默认不切换，避免把上游临时故障误判成坏 Key。

可以把完整 API Key 直接发给 Agent 吗？

不建议。让 Skill 从本地登录态同步凭据，使用本地代理 API Key（例如 local-wiscode-proxy）连接 Agent。若 Key 曾经泄露，应先刷新或撤销。

COMMUNITY / SUPPORT

遇到问题，来群里聊。

安装、模型同步、代理启动或 Agent 配置遇到卡点，欢迎加入问题沟通群。把现象和错误摘要带进来，我们一起把问题定位清楚。

使用推推扫码加群 ↗

把模型，接入你的工作台。

先把“能用”变成“好用”。