llama.cpp 本地模型接入 opencode 与 claude code：llama-server 配置与验证步骤

1. 为什么要把 llama.cpp 的本地模型接进 opencode 和 claude codellama.cpp 的llama-server能把一个 GGUF 文件变成一个 OpenAI 兼容的 HTTP 服务这件事本身不新鲜。真正让人头疼的是opencode 和 claude code 这两个命令行编程助手各自有自己的一套配置约定一个走opencode.json一个走ANTHROPIC_BASE_URL环境变量。你如果只把llama-server跑起来不去改这两个工具的配置它们根本不知道本地有个模型在等着被调用。这篇要解决的就是这个衔接问题llama-server加载本地模型之后怎么让 opencode 和 claude code 通过统一的 Key/API 通道去调用它。适合已经在本地跑过 llama.cpp、手里有 GGUF 文件、想让编程助手走本地推理的人。如果你还没装 llama.cpp先去把llama-server编译出来再回来看这篇。需要提前说清楚一件事本地小模型0.8B、1B 这个量级驱动编程助手体验和云端大模型差距很大。我实测下来0.8B 的模型在 opencode 里能列出目录文件但让它打开 DuckDB 查数据就卡住了换成 claude code 之后模型会“只说不做”输出一段计划然后停在那里。这不是配置错了是模型能力不够。所以这篇的重点是把通道打通、把请求验证成功至于模型能不能干好活那是另一回事。另外如果你希望有一个稳定的统一入口来管理 Key 和 API 通道可以了解下 TaoToken 的做法官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的思路是把不同来源的模型调用收敛到一个 Key 上本地模型和远端模型可以走同一套接入方式省得每个工具单独配一遍。2. 前置准备llama-server 启动参数与模型选择2.1 llama-server 的最小启动命令先把服务跑起来。假设你的 GGUF 文件在/par/Qwen3.5-0.8B-Q4_K_M.ggufllama.cpp 编译产物在/par/llama.cpp/build/bin/llama-server/par/llama.cpp/build/bin/llama-server \ -m /par/Qwen3.5-0.8B-Q4_K_M.gguf \ --jinja \ --ctx-size 16384 \ --host 127.0.0.1 \ --port 8033几个参数值得单独说--jinja让 llama-server 使用模型自带的 chat template。opencode 和 claude code 发过来的请求是对话格式没有这个参数模型可能把整段对话当成纯文本续写输出会乱。--ctx-size 16384是上下文窗口。注意日志里有一行n_ctx_slot 262144那是模型理论上限实际生效的是你传的--ctx-size。设太大显存吃不住设太小编程助手塞不进文件内容16384 是个折中值。--host 127.0.0.1只监听本机。如果你要让同一局域网里的另一台机器调用改成0.0.0.0但要想清楚暴露风险。启动成功的标志是日志里出现main: model loaded main: server is listening on http://127.0.0.1:8033 main: starting the main loop...看到这三行服务就算起来了。后面那些slot update_slots、prompt processing progress是请求进来之后的处理日志不用管。2.2 模型选择为什么 0.8B 不够用我试过 Qwen3.5-0.8B-Q4_K_M 和 gemma-3-1b-it-Q4_K_M 两个模型。结论很直接这个量级的模型做编程助手基本不可用。0.8B 模型在 opencode 里执行“列出当前目录全部文件”能通过因为这是个单步工具调用。但换成“打开 DuckDB 数据库、写 SQL 返回 lineitem 表行数和 l_quantity 总计数”这种多步任务它就没能执行打开数据库的动作。更离谱的是让它给 Python 脚本加注释并翻译成中文它把原文件复制了一份换个名字交差。gemma-3-1b 在 claude code 里表现稍好一点/init能输出一段 CLAUDE.md 草稿但写完就停不生成文件。日志里Brewed for 2m 26s说明它在思考但思考完没有落到工具调用上。所以模型选择上我的建议是至少 7B 起步最好 14B 以上。0.8B/1B 只适合验证通道是否打通不适合真正干活。如果你只是想确认配置对不对用哪个模型都行如果要实际用换大模型。3. opencode 配置opencode.json 骨架与 /connect 流程3.1 配置文件位置与内容opencode 的配置文件在~/.config/opencode/opencode.json。如果目录不存在就手动建mkdir -p ~/.config/opencode vi ~/.config/opencode/opencode.json内容骨架如下{ $schema: https://opencode.ai/config.json, provider: { llama.cpp: { npm: ai-sdk/openai-compatible, name: llama-server (local), options: { baseURL: http://127.0.0.1:8033/v1 }, models: { Qwen3.5-0.8B-Q4_K_M: { name: Qwen3.5-0.8B-Q4_K_M(local), limit: { context: 128000, output: 65536 } } } } } }几个关键点baseURL必须带/v1后缀。llama-server 暴露的是 OpenAI 兼容接口路径是/v1/chat/completions少写/v1会 404。npm字段指定用ai-sdk/openai-compatible这个适配器。opencode 内部用 AI SDK 做请求封装这个适配器负责把 OpenAI 格式的请求发出去。models下面的 key这里是Qwen3.5-0.8B-Q4_K_M要和 llama-server 实际加载的模型名对得上。llama-server 默认用 GGUF 文件名作为模型标识所以这里写文件名去掉.gguf后缀。limit.context和limit.output是给 opencode 做上下文管理的提示值不是硬限制。设成 128000 和 65536 是为了让 opencode 不要过早截断对话实际能塞多少还是看--ctx-size。3.2 启动 opencode 并连接本地模型配置写好后把 Node 可执行文件目录加进 PATH然后启动export PATH$PATH:/home/aaa/ccd/node-v24.14.0-linux-arm64/bin:/home/aaa/olm/bin opencode进入 opencode 界面后输入/connect命令会列出可用的 provider。找到llama-server (local)选中再选Qwen3.5-0.8B-Q4_K_M(local)。API Key 那一栏直接回车跳过本地服务不需要鉴权。连接成功后opencode 的会话界面会显示当前使用的模型。这时候你发一条“列出当前目录下的全部文件”如果模型正常它会调用工具并返回结果。3.3 实测结果与局限我这边测试“列出当前目录全部文件”是通过的。但换成 DuckDB 查询就失败了模型没能执行打开数据库的命令。后来又试了给 Python 脚本加注释并翻译模型把原文件复制了一份换名交差。这说明通道是通的请求能发到 llama-server模型也能返回内容。问题出在模型能力上0.8B 的模型无法可靠地完成多步工具调用。如果你换成 7B 以上的模型同样的配置应该能跑通更复杂的任务。4. claude code 配置环境变量与 ANTHROPIC_BASE_URL4.1 用环境变量指向 llama-serverclaude code 不读opencode.json它认的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。把 base URL 指向 llama-server 的地址export ANTHROPIC_BASE_URLhttp://localhost:8033 export ANTHROPIC_API_KEYlocal export ANTHROPIC_MODELgemma-3-1b-it-Q4_K_M claudeANTHROPIC_API_KEY填任意字符串都行llama-server 不校验。ANTHROPIC_MODEL要和 llama-server 加载的模型名一致。注意这里 base URL 不带/v1。claude code 内部会自己拼路径你给根地址就行。这一点和 opencode 不一样opencode 的baseURL要带/v1claude code 的ANTHROPIC_BASE_URL不带。这是最容易踩的坑之一。4.2 启动参数与推理预算如果你用的是带 reasoning 的模型llama-server 启动时可以加--reasoning-budget 0关掉推理链输出/par/llama.cpp/build/bin/llama-server \ -m /par/gemma-3-1b-it-Q4_K_M.gguf \ --jinja \ -c 0 \ --host 127.0.0.1 \ --port 8033 \ --reasoning-budget 0-c 0表示上下文大小从模型元数据里读不手动指定。--reasoning-budget 0让模型不输出思考过程直接给结果。对于编程助手场景思考过程会占用大量 token 和时间关掉更实用。启动日志里会看到n_parallel is set to auto, using n_parallel 4 and kv_unified true这是 llama-server 自动决定并行槽位数不用管。4.3 实测只说不做的问题用 gemma-3-1b 驱动 claude code/init命令能输出一段 CLAUDE.md 草稿内容包括 Core Commands 的说明。但输出完之后就停了没有生成文件。日志显示Brewed for 2m 26s说明模型花了 2 分多钟思考但最终没有落到工具调用上。换 Qwen3.5-0.8B 也是类似情况模型会输出一段计划然后停在那里。你问它“列出目录下的 txt 文件”它回复“我来帮你找到当前目录下所有的 .txt 文件”然后就没有然后了。这个现象的原因是claude code 期望模型返回结构化的工具调用tool use但小模型往往只能生成自然语言描述无法正确构造工具调用的 JSON。模型说“我要用 Glob 工具”但没有真正发出工具调用请求claude code 就一直在等。所以结论还是那句话本地小模型不适合驱动编程助手。通道能打通但模型能力跟不上。5. 验证请求curl 测试与成功标志5.1 用 curl 直接测 llama-server在配置 opencode 和 claude code 之前先用 curl 确认 llama-server 本身是通的curl http://127.0.0.1:8033/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3.5-0.8B-Q4_K_M, messages: [ {role: user, content: 用一句话说明什么是递归} ], max_tokens: 128 }如果返回 JSON 里有choices[0].message.content说明服务正常。如果返回 404检查 URL 是不是漏了/v1。如果返回 400检查model字段和实际加载的模型名是否一致。5.2 验证 opencode 的请求路径opencode 连接成功后你可以在 llama-server 的日志里看到请求进来的记录。正常的日志长这样slot update_slots: id 3 | task 0 | new prompt, n_ctx_slot 262144, n_keep 0, task.n_tokens 10853 slot update_slots: id 3 | task 0 | prompt processing progress, n_tokens 2048, batch.n_tokens 2048, progress 0.188704task.n_tokens 10853说明 opencode 把整个对话上下文包括系统提示、工具定义、历史消息都发过来了。progress是 prompt 处理进度到 1.0 之后开始生成。如果日志里一直没有新请求进来说明 opencode 没连上。回去检查opencode.json的baseURL和/connect流程。5.3 验证 claude code 的请求claude code 的请求也会打到 llama-server。你可以在另一个终端tail -fllama-server 的输出然后在 claude code 里发一条消息看日志有没有反应。如果 claude code 界面显示API Usage Billing但一直没有输出可能是模型在思考小模型思考很慢也可能是请求根本没发出去。等 2 分钟还没动静就 CtrlC 中断检查ANTHROPIC_BASE_URL是否设置正确。6. 常见报错排查6.1 连接被拒绝Connection refused报错信息通常是curl: (7) Failed to connect to 127.0.0.1 port 8033。原因就一个llama-server 没起来或者端口不对。排查动作ps aux | grep llama-server看进程在不在netstat -tlnp | grep 8033看端口有没有监听。如果进程在但端口没监听可能是启动时--host或--port写错了。6.2 404 Not Foundopencode 报 404九成是baseURL没带/v1。llama-server 的 OpenAI 兼容接口在/v1/chat/completions你给http://127.0.0.1:8033它会找不到路由。claude code 报 404反过来可能是ANTHROPIC_BASE_URL多带了/v1。claude code 内部会拼/v1/messages你给http://localhost:8033/v1就变成/v1/v1/messages了。6.3 模型名不匹配报错信息类似model not found或unknown model。llama-server 用 GGUF 文件名作为模型标识你配置里写的模型名必须和它一致。排查动作启动 llama-server 时看日志里main: model loaded后面有没有模型名或者直接 curlhttp://127.0.0.1:8033/v1/models列出可用模型。6.4 请求超时或卡住claude code 里发了消息界面一直转圈2 分钟没反应。这通常是小模型思考太慢或者模型在生成大量 token 但没触发工具调用。排查动作看 llama-server 日志有没有prompt processing progress在推进。如果 progress 卡在某个值不动可能是显存不够导致处理中断。如果 progress 到 1.0 之后长时间没有输出是模型在生成等就行或者换大模型。6.5 模型只输出文字不调用工具这是小模型的通病不是配置问题。模型能理解你的意图也能生成自然语言描述但无法正确构造工具调用的 JSON 结构。claude code 和 opencode 都依赖模型返回结构化的 tool use 字段小模型做不到。解决办法只有一个换更大的模型。7B 是底线14B 以上体验会好很多。如果你不想在本地跑大模型可以考虑用 TaoToken 的统一 API 通道把本地模型和远端模型放在同一套配置里管理具体接入方式看文档 https://taotoken.net/api 。7. 统一 Key/API 通道的接入思路本地模型和远端模型各配一套管理起来很麻烦。opencode 要改opencode.jsonclaude code 要改环境变量每换一个模型就得动一次配置。一个更省事的做法是用统一的 API 通道。TaoToken 的模型对话入口 https://taotoken.net/api 支持 OpenAI 兼容格式你可以把 opencode 的baseURL指向它把 claude code 的ANTHROPIC_BASE_URL也指向它Key 用同一个。这样本地模型和远端模型走同一套接入逻辑切换模型只需要改模型名不用动配置结构。如果你要长期用编程助手干活建议走 Coding Plan 这条路把 Key 管理和模型切换都收敛到一个地方。API Keys 在控制台里生成接入文档里有 opencode 和 claude code 的配置示例照着改就行。本地 llama.cpp 适合做实验和验证真正日常使用还是得靠稳定的 API 通道加上足够大的模型。小模型能跑通流程但干不了活这一点我踩过坑你不用再踩一遍。