Olares

简体中文

English

简体中文

English

外观

WARNING

本文档由 AI 自动翻译，仅供参考。涉及关键操作或信息时，请以英文原文为准。

使用 Claude Code 编写代码 ​

Claude Code 是一个 AI 编码助手，帮助你使用自然语言编写、测试和管理代码。在 Olares 上，这个命令行界面运行在基于浏览器的终端中，配备了预配置的 Ubuntu 开发环境。

学习目标 ​

在本指南中，你将学习如何：

  • 从 Olares Market 安装 Claude Code 应用。
  • 使用 Anthropic 订阅或本地模型将 Claude Code CLI 连接到模型。
  • 执行基本和高级的自然语言编码工作流程。
  • 安全地管理软件依赖。

前提条件 ​

开始前，你需要：

  • 一台运行 Olares 1.12.7 或更高版本、具有足够磁盘空间和内存的 Olares 设备。

  • 使用本地模型时，能够访问 Router。

  • 根据连接方式，还需准备以下内容：

    连接方式所需条件
    Anthropic 订阅有效的 Claude Pro 或 Max 订阅
    本地模型已从 Market 安装 Qwen3.8-27B (llama.cpp)
可选：使用其他模型

从应用市场安装其他聊天模型，或通过引擎基座应用创建模型实例，然后在 Router 的 Default models 页面将其设为默认聊天模型。使用 default-chat 的客户端会调用新的默认模型，无需修改客户端的模型设置。

如果希望某个客户端始终使用指定模型，可改填 Router 的 How to call this model 窗口中显示的完整模型名称。

模型兼容性

部分本地模型（包括 Qwen3.5-9B-GGUF Q4_K_M (llama.cpp)）使用的聊天模板不兼容 Claude Code 的系统消息顺序。如果遇到系统消息相关报错，请切换到其他模型。原因详见常见问题。

安装 Claude Code ​

  1. 打开 Market，并搜索 "Claude Code"。

    Claude Code

  2. 点击 Get，然后点击 Install。等待安装完成。

连接到模型 ​

启动 Claude Code CLI 并将其连接到语言模型。选择以下连接方法之一。

使用 Anthropic 订阅连接 ​

如果你持有活跃的 Claude Pro 或 Max 订阅，请使用此方法。

  1. 从 Launchpad 打开 Claude Code CLI。

  2. 输入以下命令：

    bash
    claude

  3. 选择终端主题，例如 Dark mode，然后按 Enter。

  4. 选择 Claude account with subscription 作为登录方法，然后按 Enter。浏览器窗口将打开以进行登录。如果浏览器未能打开，请点击提供的 URL 手动登录。

    使用订阅账户登录 Claude Code

  5. 在浏览器中完成登录流程，然后复制认证代码。

  6. 返回终端，粘贴代码，然后按 Enter 完成登录。

  7. 查看 Accessing workspace: /opt/data 安全提示，然后选择 Yes, I trust this folder。

    终端用户界面（TUI）自动打开。

    Claude Code TUI

使用本地模型连接 ​

使用此方法在本地运行 Claude Code。此示例使用模型应用 Qwen3.8-27B (llama.cpp)。

模型连接的工作原理

在 Olares 1.12.7 及以上版本中，AI 客户端通过 Olares Router 连接模型。Router 提供 Base URL，并将 default-chat 的请求转发给**默认模型（Default models）**页面中设置的聊天模型。

本教程使用 Qwen3.8-27B (llama.cpp) 作为默认聊天模型。连接格式和 API 密钥要求详见连接 AI 应用。

  1. 从启动台打开 Router。在 Default models 页面将 Qwen3.8-27B (llama.cpp) 设为默认聊天模型。

  2. 进入 LLM 页面，找到 Qwen3.8-27B (llama.cpp)，点击模型所在行的 View connection example 图标。

  3. 在 How to call this model 窗口中，选择 Apps in Olares，复制 Base URL，然后去掉末尾的 /v1，供 Anthropic 兼容客户端使用。例如填写 https://router.<你的 Olares 域名>。客户端会自动追加 /v1/messages。

  4. 模型名称使用 default-chat。

    在应用中选择模型

    default-chat 是路由名称，不会出现在从 Router 获取的模型列表中。如果要连接 Router 的应用会加载模型列表，请手动添加 default-chat。如果应用只允许选择列表中的模型，请选择 Router 的 How to call this model 窗口中显示的完整模型名称。

  5. API 密钥留空。如果要连接 Router 的应用要求填写此字段，请填入 olares。

  6. 打开 Olares Settings，前往 Applications > Claude Code > Manage environment variables。

  7. 设置以下环境变量：

    • ANTHROPIC_AUTH_TOKEN: 填写 olares。
    • ANTHROPIC_BASE_URL: 输入从 Router 复制的 Base URL。例如，https://router.<your-olares-domain>。
    • ANTHROPIC_MODEL: 填写 default-chat。

  8. 点击 Apply。等待约 10 秒让容器重启。

  9. 从 Launchpad 打开 Claude Code CLI，然后在终端中输入 claude 以启动你的会话。

使用 Claude Code ​

所有项目工作都在 /opt/data 目录中进行，该目录在容器中作为 $HOME。此目录在应用重启之间持久保存你的文件。

以下示例演示如何与 Claude Code 交互以完成日常开发任务。

运行基本查询 ​

  1. 在 Claude Code CLI 中，输入以下命令：

    bash
    claude

  2. 选择最适合你终端的文本样式，例如 dark mode。

  3. 查看安全提示，然后按 Enter 继续。

  4. 查看 Accessing workspace: /opt/data 安全提示，然后选择 Yes, I trust this folder 以授予 Claude Code 读取、编辑和执行权限。

  5. （可选）在 TUI 中，运行 /clear 命令以使用空上下文开始新会话。

    Claude Code 首次聊天

    在模式之间切换

    如果你在远程和本地模型之间切换，先在 Claude Code 中运行 /clear 再开始新会话。这可以防止先前模型的上下文影响新工作空间。

  6. 用自然语言描述你的任务。例如：

    text
    List the files in the current directory

    助手自动执行必要的内部命令来探索目录，并返回你的文件的详细列表。

    Claude Code 首次聊天结果

  7. 查看结果。

构建全栈项目 ​

Claude Code 可以创建多服务项目、运行测试并验证端到端集成。

以下示例演示如何使用单个 Node.js Express 服务器构建轻量级的 "Hello Olares" 网页应用，该服务器同时处理后端 API 和前端显示。

  1. 在 Claude Code TUI 中，输入以下提示：

    text
    Create a simple full-stack "Hello Olares" application in a new directory called `hello-olares`.

Please do the following:
1. Initialize a Node.js project and install the `express` package.
2. Create a backend API (`server.js`) that runs on port 3000 and has a single endpoint `/api/message` returning `{"message": "Hello Olares!"}`.
3. Create a frontend (`public/index.html`) with vanilla JavaScript that fetches the message from the API and displays it on the screen. Configure the server to serve this static directory.
4. Start the server in the background, use `curl` to verify the `/api/message` endpoint works, and then stop the server cleanly.

  2. 等待 Claude Code 处理提示。助手自动初始化项目、安装 Express、编写代码、启动服务器并执行实时 curl 集成检查。

  3. 当助手提示你允许继续时，选择 Yes, and don't ask again...。你可能需要为不同类型的操作批准多个提示。

  4. 查看助手返回的最终摘要报告。它概述了新创建的项目结构、配置的后端 API、前端设置以及成功的 curl 测试结果。

    Claude Code 编码项目结果

管理安全和开发环境 ​

Claude Code 容器在严格的最小权限设置下运行以确保安全。

主进程和所有执行的命令使用非 root 用户（UID/GID 1000）。容器禁用 allowPrivilegeEscalation 并丢弃所有 Linux 功能。因此，sudo 和 apt install 等管理命令不可用。

查看预装的开发工具 ​

在安装额外软件之前，请查看工作空间中已包含的工具。容器镜像基于 Ubuntu 24.04，并预装了许多常见的开发工具。

下表列出了主要类别和示例。

类别包含的工具
语言和运行时Python 3, Node.js, Go, Rust, Java (OpenJDK 21), Ruby, PHP 8.3,
Lua, Perl, SQLite
构建工具build-essential, cmake, ninja-build, clang, pkg-config,
常见 -dev 头文件
CLI 工具git, git-lfs, curl, wget, jq, yq, openssh-client, unzip,
zip, rsync, tmux, htop, shellcheck
数据库客户端postgresql-client, mysql-client, redis-tools

INFO

ripgrep (rg) 工具被有意排除，以防止与 Claude Code 的原生搜索行为冲突。

安装额外软件 ​

如果你的项目需要预装工具之外的工具或库，你必须在容器的安全边界内管理它们。

你无法自行安装的内容 ​

如果你的项目需要系统级库（例如 libpq-dev、ffmpeg、libssl-dev），你无法直接安装它们。这些依赖必须由应用维护者添加到基础容器镜像中。

你可以在工作空间中安装的内容 ​

在你的可写目录（主要是 /opt/data）中，你可以使用常见工具在没有 root 权限的情况下安装项目级依赖：

  • Python: 创建虚拟环境并使用 pip。例如：

    bash
    python3 -m venv .venv
source .venv/bin/activate
pip install <package>

  • Node.js: 在你的项目文件夹中使用 npm。例如：

    bash
    npm install <package>

  • Rust/Go（或其他编译语言）：将二进制文件安装到用户可写的路径。例如：

    bash
    cargo install --root ~/.local <package>   # Rust
go install <package>@latest               # Go (安装到 ~/go/bin)

INFO

容器预配置环境变量 PIP_BREAK_SYSTEM_PACKAGES=1。虽然这允许系统范围的 Python 包安装，但建议使用虚拟环境以保持工作空间整洁和可靠。

常见问题 ​

System message must be at the beginning. ​

当模型的聊天模板仅允许系统消息出现在对话开头时，会出现此错误。Claude Code 可能在对话后续位置发送额外的系统消息。有此限制的模板会拒绝这些消息，导致 HTTP 500 错误和反复重试。

claude: command not found ​

等待片刻让 init 容器完成 Claude Code 的安装。验证 $HOME/.local/bin 目录是否存在于你的系统 PATH 中。

OAuth 或安装脚本失败 ​

验证你的 Olares 集群的出站网络连接。init 容器需要互联网访问才能从 https://claude.ai/install.sh 下载依赖。

缺少语言或库 ​

确定缺失的工具是系统级依赖还是用户级依赖：

  • 系统级依赖：你无法自行安装这些。应用维护者必须将它们添加到基础镜像中。如果你需要当前不可用的系统级库，请提交 GitHub Issue 请求添加。
  • 用户级依赖：使用 venv、npm install 或类似的本地工具来安装它们。

了解更多 ​