企业官网建设流程全解析

1. 鸿蒙 PC 上的 AI Agent 生态现状

1.1 为什么要在鸿蒙 PC 上跑 AI Agent

鸿蒙 PC 版从正式亮相到现在，我一直在真机上折腾各种开发工具链。说实话，最开始我对它的定位是"能跑就行"，但用了几个月之后发现，这台机器在 AI Agent 场景下的表现比我预期好不少。原因有三点：第一，鸿蒙的微内核架构在资源调度上确实有优势，后台挂一个 Agent 进程再开 IDE，内存占用比同配置的 Windows 机器低一截；第二，鸿蒙原生支持分布式软总线，意味着你的 Agent 可以跨设备调用手机、平板甚至 IoT 设备的算力，这在多端协同场景下很有想象力；第三，终端环境是类 Unix 的，大部分命令行工具迁移过来只需要重新编译，不需要大改。

但问题也很明显——生态太新了。很多主流 AI Agent 工具压根没有鸿蒙原生版本，官方文档里也找不到安装指引。我踩过的坑包括但不限于：Node 版本不兼容导致 Claude Code 装完跑不起来、Codex CLI 的二进制在鸿蒙上缺动态库、某些依赖 Python 的 Agent 框架因为底层库编译问题直接卡死。所以这篇文章的核心目的，就是把我实测能跑通的工具、跑不通的原因、以及绕过去的方案全部整理出来，让后来的人少走弯路。

这篇文章适合三类人看：一是手里已经有鸿蒙 PC 或者准备入手的开发者，想知道这台机器到底能不能当 AI 开发主力机；二是正在做鸿蒙应用开发、想在自己的 App 里集成 AI Agent 能力的工程师；三是对 AI Agent 感兴趣、想找一个相对干净的环境来折腾的爱好者。不管你是哪种，我都会尽量把每一步写清楚，包括我用的具体版本号、遇到的报错信息、以及最终怎么解决的。

1.2 当前可用的工具全景速览

先给一个全局视角。截至我写这篇文章的时候，在鸿蒙 PC 上能比较顺畅跑起来的 AI Agent 相关工具，大致可以分成四类：

这个表格里的"支持情况"是我个人实测的结论，不是官方声明。比如 Claude Code，官方并没有说支持鸿蒙，但它本质是一个 Node.js 应用，只要 Node 环境配好，就能跑。Codex CLI 稍微麻烦一点，因为它是 Rust 编译的二进制，需要确认鸿蒙的 glibc 版本和动态链接库是否匹配。LangChain 这类 Python 框架反而最简单，因为 Python 的跨平台性最好，pip 能装的基本都能跑。

注意：鸿蒙 PC 目前有两个分支——一个是华为官方的 HarmonyOS PC 版，一个是开源鸿蒙（OpenHarmony）的 PC 移植版。两者的底层虽然同源，但软件包管理和系统调用接口有差异。我下面提到的所有操作，如果没有特别说明，都是在开源鸿蒙 PC 版上验证的。官方版的操作逻辑类似，但部分命令可能需要调整。

2. 环境准备：从零搭建可用的终端环境

2.1 系统版本确认与基础依赖安装

在装任何 AI Agent 工具之前，先把系统底子打好。这一步很多人会跳过，结果后面遇到各种莫名其妙的报错。我建议你按顺序执行以下检查：

第一，确认系统版本和架构。打开终端，执行：

uname -a cat /etc/os-release

你需要关注两个信息：内核版本和 CPU 架构。目前鸿蒙 PC 主要跑在 ARM64（比如麒麟系列）和 x86_64（开源鸿蒙的 PC 移植版）两种架构上。这直接决定了你后面下载二进制文件时选哪个版本。我曾经在一个 x86 的鸿蒙虚拟机上装了 ARM 版的 Node，结果自然是跑不起来，浪费了半小时。

第二，安装基础编译工具链。鸿蒙 PC 默认可能没有完整的 build-essential，需要手动补：

sudo apt update sudo apt install -y build-essential git curl wget python3 python3-pip

如果你用的是开源鸿蒙的包管理器，命令可能是ohpm或者hpm，具体看你刷的哪个镜像。我用的那个版本是基于 Debian 的，所以 apt 还能用。如果你的系统里没有 apt，那就需要先通过 Harmonybrew 来装这些基础工具。

第三，配置 Node.js 环境。这是跑 Claude Code 和大部分 Agent 工具的前提。我强烈建议不要用系统自带的 Node，版本太老。用 nvm 来管理：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v

这里选 Node 20 是有原因的。Claude Code 官方要求 Node 18 以上，但我实测 Node 20 的兼容性最好，Node 22 在某些鸿蒙的库环境下会有 SSL 相关的问题。装完之后记得把 nvm 的初始化脚本加到.bashrc或者.zshrc里，不然每次开新终端都要重新 source。

2.2 Harmonybrew 的安装与配置

Harmonybrew 是我在鸿蒙 PC 上发现的最实用的包管理工具，相当于 macOS 上的 Homebrew。它解决了一个核心痛点：很多 AI Agent 工具依赖的底层库（比如 openssl、sqlite、ffmpeg）在鸿蒙的官方源里要么没有，要么版本不对。Harmonybrew 把这些都打包好了，一条命令就能装。

安装方法很简单：

/bin/bash -c "$(curl -fsSL https://harmonybrew.com/install.sh)"

装完之后需要把 Harmonybrew 的路径加到环境变量里：

echo 'eval "$(/opt/harmonybrew/bin/brew shellenv)"' >> ~/.bashrc source ~/.bashrc brew --version

如果能看到版本号输出，说明安装成功。接下来我建议先装几个常用的依赖：

brew install openssl sqlite3 ffmpeg ripgrep

ripgrep特别重要，因为 Claude Code 内部用 rg 来做代码搜索，如果系统里没有，它会报错或者降级到很慢的搜索方式。openssl则是很多网络请求库的底层依赖，鸿蒙自带的版本有时候缺某些加密算法。

实操心得：Harmonybrew 的源在国内访问速度还可以，但偶尔会抽风。如果安装过程中卡住，可以试试换源，具体方法是在~/.harmonybrewrc里加上国内镜像地址。不过这个镜像地址经常变，建议去 Harmonybrew 的官方社区看最新的。

2.3 终端环境的美化与效率工具

虽然这一步不是必须的，但一个好的终端环境能显著提升你折腾 Agent 的效率。我在鸿蒙 PC 上用的是zsh+oh-my-zsh+starship的组合：

brew install zsh starship chsh -s $(which zsh) sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

然后在.zshrc里加上eval "$(starship init zsh)"。Starship 的好处是它会自动显示当前目录的 git 状态、Node 版本、Python 虚拟环境等信息，你在多个 Agent 项目之间切换的时候不容易搞混。

另外强烈建议装一个tmux：

brew install tmux

为什么？因为跑 AI Agent 的时候经常需要同时开好几个终端窗口——一个跑 Agent 主进程，一个看日志，一个手动执行命令调试。tmux 可以让你在一个 SSH 会话里管理多个窗格，而且即使终端断开，Agent 进程也不会被杀掉。我有一次跑一个长任务，忘了开 tmux，结果网络波动导致 SSH 断连，跑了半小时的任务直接没了，血的教训。

3. Claude Code 在鸿蒙 PC 上的完整部署

3.1 安装与首次配置

Claude Code 是目前在鸿蒙 PC 上体验最好的终端型 Coding Agent，没有之一。它的安装本身不复杂，但鸿蒙环境下有几个坑需要提前知道。

安装命令：

npm install -g @anthropic-ai/claude-code

装完之后执行claude --version，如果能看到版本号，说明二进制没问题。但第一次运行claude的时候，它可能会报错说找不到某些动态库。我遇到的是缺libssl.so.3，解决方法是用 Harmonybrew 装 openssl 之后，手动建一个软链接：

sudo ln -s /opt/harmonybrew/lib/libssl.so.3 /usr/lib/libssl.so.3 sudo ln -s /opt/harmonybrew/lib/libcrypto.so.3 /usr/lib/libcrypto.so.3

然后重新运行claude，应该就能进入交互界面了。首次使用需要登录，Claude Code 支持两种认证方式：一种是直接登录 Anthropic 账号，另一种是用 API Key。如果你在国内，直接登录可能会遇到网络问题，这时候可以用 API Key 的方式，在环境变量里设置：

export ANTHROPIC_API_KEY="your-api-key-here"

注意：API Key 不要直接写在.bashrc里然后提交到 git。建议用一个单独的.env文件，然后加到.gitignore。我见过有人把 Key 推到公开仓库，结果被扫到之后一夜之间跑了上千美元的账单。

3.2 接入本地模型：LM Studio 的配置方法

Claude Code 默认是调用 Anthropic 的云端模型，但如果你有隐私需求或者想省钱，可以把它接到本地跑的模型上。LM Studio 是我在鸿蒙 PC 上测试下来最稳定的本地推理工具，它提供了一个 OpenAI 兼容的 API 接口。

首先装 LM Studio：

brew install --cask lm-studio

打开之后，在模型市场里下载一个适合你硬件配置的模型。鸿蒙 PC 如果是 16GB 内存，建议跑 7B 左右的量化模型，比如 Qwen2.5-7B-Instruct 的 Q4 版本。下载完之后，在 LM Studio 的 "Local Server" 标签页里启动服务，默认端口是 1234。

然后配置 Claude Code 使用这个本地接口。Claude Code 本身不直接支持 OpenAI 格式的 API，但可以通过设置ANTHROPIC_BASE_URL来指向一个兼容层。我用的方案是跑一个轻量的代理转换服务：

npm install -g openai-to-anthropic-proxy openai-to-anthropic-proxy --port 8080 --target http://localhost:1234/v1

然后在另一个终端里：

export ANTHROPIC_BASE_URL="http://localhost:8080" export ANTHROPIC_API_KEY="dummy-key" claude

这样 Claude Code 就会把请求发到本地的 LM Studio 上。实测下来，7B 模型在代码补全和简单重构任务上够用，但复杂逻辑推理还是差点意思。如果你有 32GB 内存，可以试试 14B 的模型，体验会好很多。

3.3 VS Code 集成与终端命令执行

Claude Code 有一个 VS Code 扩展，可以在编辑器里直接调用。在鸿蒙 PC 上装 VS Code 本身就需要一点技巧，因为官方没有提供鸿蒙版的安装包。我的做法是用 Harmonybrew 装一个社区维护的版本：

brew install --cask vscode-oss

装完之后，在 VS Code 的扩展市场里搜索 "Claude Code"，安装官方扩展。然后在设置里配置claude-code.executablePath指向你刚才装的claude二进制路径。

Claude Code 最强大的功能之一是它能直接执行终端命令。比如你让它"帮我看看当前目录下哪个文件最大"，它会自动跑du -sh * | sort -rh | head -5然后把结果解读给你。这个功能在鸿蒙 PC 上完全可用，但有一个前提：你的终端环境变量要配好，不然它执行的命令可能找不到路径。

我遇到过一个典型问题：Claude Code 执行npm install的时候报错说找不到 npm。原因是它用的 shell 是/bin/sh，而我的 nvm 配置只写在了.bashrc里。解决方法是在.profile里也加上 nvm 的初始化脚本，因为/bin/sh会读.profile。

4. Codex CLI 与其他 Agent 工具的适配

4.1 Codex CLI 安装与常见报错处理

Codex CLI 是另一个我很常用的终端 Agent，它的优势是启动速度快、对系统资源占用低。但它在鸿蒙 PC 上的安装比 Claude Code 麻烦，因为它是 Rust 编译的二进制，对系统库的版本比较敏感。

安装方式有两种。第一种是用 npm：

npm install -g @openai/codex

第二种是直接下载二进制。我推荐第二种，因为 npm 装的时候有时候会编译原生模块，在鸿蒙上容易失败。去 Codex CLI 的 release 页面下载对应架构的二进制，然后：

chmod +x codex sudo mv codex /usr/local/bin/ codex --version

如果运行时报GLIBC_2.xx not found，说明你的鸿蒙系统 glibc 版本太低。这时候要么升级系统，要么用 Harmonybrew 装一个更新的 glibc 然后通过LD_LIBRARY_PATH指定。我用的后者：

brew install glibc export LD_LIBRARY_PATH="/opt/harmonybrew/lib:$LD_LIBRARY_PATH"

把这个 export 加到.bashrc里，不然每次开新终端都要重新设。

Codex CLI 的常用命令我整理了一个速查表：

这几个命令在鸿蒙 PC 上都能正常用。我特别喜欢/compact，因为鸿蒙 PC 的内存相对有限，长时间对话之后上下文会占很多内存，compact 一下能释放不少。

4.2 基于 Rust 的轻量 Agent 工具尝试

除了 Claude Code 和 Codex CLI，我还试过几个基于 Rust 的轻量 Agent 工具，比如aichat和shell-gpt。这类工具的特点是二进制小、启动快、依赖少，在鸿蒙 PC 上跑起来很舒服。

以aichat为例：

brew install aichat aichat --help

它支持多种模型后端，配置方式是在~/.config/aichat/config.yaml里写：

model: openai:gpt-4 clients: - type: openai api_key: your-key api_base: https://api.openai.com/v1

如果你用本地模型，把api_base改成 LM Studio 的地址就行。aichat的好处是它有一个-e参数，可以直接执行 shell 命令：

aichat -e "找出当前目录下所有超过 100MB 的文件"

它会生成命令并询问你是否执行。这个功能在鸿蒙 PC 上很实用，因为鸿蒙的终端命令和标准 Linux 有些差异，有时候你记不清某个命令的具体参数，让 Agent 帮你生成比查文档快。

4.3 Agent 开发框架的依赖调优

如果你不只是想用现成的 Agent 工具，而是想自己开发 Agent，那 LangChain、LangGraph、Spring AI 这些框架在鸿蒙 PC 上的适配就很重要了。

Python 系的框架（LangChain、LangGraph）基本无障碍，因为 Python 的跨平台性最好。我实测 LangChain 0.3.x 在鸿蒙 PC 上跑得很稳，只需要注意一点：某些依赖包（比如numpy、pandas）在 ARM 架构上需要从源码编译，装的时候会比较慢。建议用pip install --prefer-binary来优先使用预编译的 wheel。

Java 系的 Spring AI 稍微麻烦一点，因为需要 JDK。鸿蒙 PC 上可以装 OpenJDK：

brew install openjdk@21

然后配置JAVA_HOME。Spring AI 的依赖解析本身没问题，但如果你用到某些 native 库（比如做向量检索的），可能需要额外编译。

避坑技巧：在鸿蒙 PC 上装 Python 包的时候，如果遇到error: command 'gcc' failed，大概率是缺python3-dev。用sudo apt install python3-dev补上就行。另外，建议用venv而不是conda，因为 conda 在鸿蒙上的兼容性不如 venv 稳定。

5. 实操案例：用 Claude Code 在鸿蒙 PC 上开发一个 Django 项目

5.1 项目初始化与 Agent 协作流程

光说工具怎么装没意思，我拿一个真实项目来演示整个流程。需求很简单：用 Django 写一个待办事项 API，支持增删改查。我全程用 Claude Code 来辅助开发，记录下每个环节的实际体验。

首先创建项目目录并初始化：

mkdir todo-api && cd todo-api python3 -m venv venv source venv/bin/activate pip install django djangorestframework django-admin startproject todoapi . python manage.py startapp todos

然后启动 Claude Code：

claude

在交互界面里，我输入的第一条指令是："帮我配置 Django REST framework，创建一个 Todo 模型，字段包括 title、completed、created_at，然后生成对应的 serializer 和 viewset。"

Claude Code 会先读取当前目录的文件结构，然后生成代码。它修改了settings.py添加rest_framework和todos到INSTALLED_APPS，创建了todos/models.py、todos/serializers.py、todos/views.py，还更新了todoapi/urls.py注册路由。整个过程大概花了 30 秒，比我手动写快很多。

但这里有一个坑：Claude Code 生成的代码默认用的是django.contrib.auth的用户模型，如果你还没有跑migrate，它会报错。所以正确的顺序是先生成代码，然后手动跑：

python manage.py makemigrations python manage.py migrate

5.2 数据库迁移与接口测试

迁移完成之后，用 Claude Code 生成测试用例：

claude "为 todos 应用生成 pytest 测试用例，覆盖 CRUD 所有接口"

它会创建todos/tests.py，里面包含用pytest-django写的测试。但你需要先装 pytest：

pip install pytest pytest-django

然后在pytest.ini里配置DJANGO_SETTINGS_MODULE。Claude Code 会自动帮你创建这个文件，但有时候它会忘记加--ds参数，导致 pytest 找不到 Django 配置。如果遇到这个问题，手动在pytest.ini里加上：

[pytest] DJANGO_SETTINGS_MODULE = todoapi.settings python_files = tests.py test_*.py *_tests.py

跑测试：

pytest -v

我实测下来，Claude Code 生成的测试用例大概有 80% 能直接跑通，剩下 20% 需要微调，主要是断言条件写得太严格或者 URL 路径拼错。但即使这样，也省了我至少一半的时间。

5.3 性能调优与 Agent 的边界

项目跑起来之后，我用ab（Apache Bench）做了一轮压力测试：

ab -n 1000 -c 10 http://127.0.0.1:8000/api/todos/

结果发现 QPS 只有 200 左右，对于一个小 API 来说偏低。我让 Claude Code 分析瓶颈，它建议加数据库索引和启用查询缓存。我按照它的建议在completed字段上加了db_index=True，QPS 提升到了 350 左右。

但这里也暴露了 Agent 的边界：它给出的优化建议是通用性的，没有考虑到鸿蒙 PC 上 SQLite 的写入性能本身就有瓶颈。如果要进一步优化，需要换 PostgreSQL，但 PostgreSQL 在鸿蒙上的安装又是另一个坑。所以我的体会是，Agent 能帮你做 70% 的常规工作，但最后 30% 的深度优化还是得靠人。

6. 常见问题与排查技巧实录

6.1 安装类问题速查

6.2 运行类问题与性能优化

Agent 跑起来之后，最常见的问题是响应慢。在鸿蒙 PC 上，响应慢通常有三个原因：一是模型本身太大，硬件带不动；二是网络请求走了代理，延迟高；三是系统内存不足，频繁 swap。

排查方法：先用htop看 CPU 和内存占用。如果内存占用超过 80%，说明需要换更小的模型或者加内存。如果 CPU 占用高但内存正常，可能是模型推理本身的计算量大，可以考虑用量化程度更高的模型（比如从 Q4 换成 Q2）。

网络方面，如果你用的是云端 API，可以在终端里curl -w "@curl-format.txt" -o /dev/null -s https://api.anthropic.com来测延迟。curl-format.txt的内容是：

time_namelookup: %{time_namelookup}\n time_connect: %{time_connect}\n time_starttransfer: %{time_starttransfer}\n time_total: %{time_total}\n

如果time_connect超过 500ms，说明网络链路有问题，可以考虑换一个 API 端点或者用本地模型。

6.3 独家避坑经验分享

第一个坑：不要在鸿蒙 PC 上同时跑多个 Agent。我有一次同时开了 Claude Code 和 Codex CLI，两个都在跑代码生成任务，结果内存直接爆了，系统卡死。后来我养成了习惯，跑重任务之前先free -h看一下可用内存，不够就先关掉其他应用。

第二个坑：鸿蒙的终端默认编码可能不是 UTF-8。我有一次让 Agent 生成包含中文注释的代码，结果保存出来全是乱码。解决方法是在.bashrc里加上：

export LANG=en_US.UTF-8 export LC_ALL=en_US.UTF-8

第三个坑：Harmonybrew 装的某些库和系统自带的库版本冲突。比如系统自带的libcurl和 brew 装的libcurl同时存在时，某些程序会链接到错误的版本。排查方法是ldd $(which claude)看它实际链接的是哪个路径的库。如果发现链接到了系统路径但版本不对，可以用LD_PRELOAD强制指定。

第四个坑：Claude Code 的/compact命令在鸿蒙上偶尔会卡住。我分析下来是因为它要调用一个外部进程来压缩上下文，而那个进程在鸿蒙上的启动速度比较慢。如果卡住超过 10 秒，直接 Ctrl+C 然后重新进就行，对话历史不会丢。

7. 后续扩展与持续更新计划

7.1 值得关注的新工具与方向

鸿蒙 PC 的 AI Agent 生态变化很快，我目前关注几个方向。一是华为自己在推的盘古大模型和鸿蒙的深度集成，如果官方能出一个原生的 Agent 运行时，那体验会比现在用第三方工具好很多。二是一些基于 Rust 的新兴 Agent 框架，比如rig和swiftide，它们的二进制体积小、启动快，很适合鸿蒙这种资源受限的环境。三是 MCP（Model Context Protocol）的普及，如果更多工具支持 MCP，那在鸿蒙上集成不同 Agent 的成本会大幅降低。

我自己的计划是每个月更新一次这篇文章，把新测通的工具加进来，把失效的方法标注出来。如果你也在鸿蒙 PC 上折腾 AI Agent，欢迎交流你踩过的坑和跑通的方案。

7.2 给不同阶段读者的建议

如果你是刚入手鸿蒙 PC 的新手，我的建议是先别急着装一堆工具。先把 Node、Python、Harmonybrew 这三个基础环境配好，然后从 Claude Code 开始，跑通一个最简单的"让 Agent 帮我写一个 Hello World"的流程。有了这个正反馈之后，再逐步尝试本地模型和自定义 Agent 开发。

如果你是有经验的开发者，想用鸿蒙 PC 做主力开发机，那我的建议是做好心理准备：你会遇到很多在 macOS 和 Linux 上不会遇到的问题，但解决这些问题的过程本身也是学习。而且鸿蒙的分布式能力确实有独特价值，如果你的项目涉及多端协同，那这台机器值得投入时间。

如果你是在做鸿蒙应用开发，想在自己的 App 里集成 AI 能力，那建议直接看华为官方的 AI 框架文档，第三方 Agent 工具更多是辅助开发的角色，不是最终产品的一部分。

最后分享一个小技巧：在鸿蒙 PC 上跑 Agent 的时候，把~/.cache目录挂到一个 tmpfs 上，能显著减少磁盘 I/O。具体做法是在/etc/fstab里加一行：

tmpfs /home/youruser/.cache tmpfs defaults,size=2G 0 0

然后sudo mount -a。这样 Agent 产生的临时文件都在内存里，速度快很多，而且重启自动清理。我实测下来，Claude Code 的响应速度大概能快 15% 左右。